@thawgate/sdk 0.0.0-stage → 0.1.0

package/dist/reasons.d.mts

@@ -0,0 +1,95 @@
+/**
+ * @module gate/reasons
+ * @description ThawGate's reason codes and the one parser for them.
+ *
+ * On every thaw and freeze decision the gate logs `TG:ALLOW:<CODE>` or `TG:DENY:<CODE>`
+ * (programs/thawgate-gate/src/decision.rs). `explain()`, `freezeIfInvalid()` and the keeper all read a transaction's
+ * logs through {@link classifyGateLogs}, so a wallet's reason is computed one way everywhere.
+ *
+ * This module has no imports. Services that don't want the SDK's Solana dependencies load it on its own:
+ * `import { classifyGateLogs } from "@thawgate/sdk/reasons"`.
+ */
+/** The ThawGate gating program (devnet). The same value as `THAWGATE_GATE_PROGRAM_ID`, as a string. */
+declare const THAWGATE_GATE_ID = "THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ";
+/** Which Token ACL permissionless instruction called the gate. */
+type GateAction = "thaw" | "freeze";
+/** Why a thaw passes (`TG:ALLOW:<code>` on thaw). */
+declare const THAW_ALLOW_CODES: readonly ["KYC", "PDA_ALLOWLISTED", "ALLOWLISTED", "CLEAN"];
+/** A policy flag on the owner: `TG:DENY:<code>` on thaw, `TG:ALLOW:<code>` on freeze. */
+declare const FLAG_CODES: readonly ["BLACKLISTED", "NOT_ALLOWLISTED", "NO_CREDENTIAL", "CREDENTIAL_EXPIRED", "KYC_LEVEL_TOO_LOW"];
+/** Denied before any policy decision, on thaw and on freeze. */
+declare const STRUCTURAL_DENY_CODES: readonly ["MISSING_ACCOUNTS", "BAD_POLICY", "BAD_REGISTRY_ENTRY", "BAD_CREDENTIAL"];
+type ThawAllowCode = (typeof THAW_ALLOW_CODES)[number];
+type FlagCode = (typeof FLAG_CODES)[number];
+type StructuralDenyCode = (typeof STRUCTURAL_DENY_CODES)[number];
+/** Every code the gate logs. `NO_IMMUTABLE_OWNER` denies a thaw only; `COMPLIANT` denies a freeze only. */
+type TgCode = ThawAllowCode | FlagCode | StructuralDenyCode | "NO_IMMUTABLE_OWNER" | "COMPLIANT";
+/**
+ * The gate's custom error number for each `TG:DENY` code (errors.rs `Denied*`, 6009–6019). Used only when a
+ * simulation's logs were cut before the gate's own line.
+ */
+declare const GATE_DENY_ERRORS: Readonly<Record<number, TgCode>>;
+declare function isTgCode(code: string): code is TgCode;
+/**
+ * A human sentence for a gate decision, e.g. `describe("DENY", "NO_CREDENTIAL", "thaw")` →
+ * "Unlock denied: the owner has no SAS attestation …". The action matters: BLACKLISTED denies a thaw but allows a freeze.
+ */
+declare function describe(decision: "ALLOW" | "DENY", code: string, action: GateAction): string;
+interface GateLogs {
+    /** A frame of the gating program appears in the logs. */
+    gateInvoked: boolean;
+    /** The gate's `TG:` line: the first one inside one of its own frames. */
+    decision: {
+        kind: "ALLOW" | "DENY";
+        code: string;
+    } | null;
+    /** The first `Program <id> failed: <message>` line. */
+    failure: {
+        program: string;
+        message: string;
+    } | null;
+}
+/**
+ * Reads a transaction's (or a simulation's) logs. Only `TG:` lines logged inside the gate's own frames count, so a
+ * different gating program can't impersonate a ThawGate decision. The first match wins: the gate's `msg!` line comes
+ * before Anchor's error line, which repeats the code.
+ */
+declare function parseGateLogs(logs: readonly string[], gateId?: string): GateLogs;
+/** The gate's verdict on one thaw or freeze transaction. */
+type GateVerdict = 
+/** The gate allowed it (a thaw unlocked the account, or a freeze froze it). */
+{
+    outcome: "allowed";
+    code: string;
+    reason: string;
+}
+/** The gate denied it. On freeze, `COMPLIANT` means the owner passes the policy. */
+ | {
+    outcome: "denied";
+    code: string;
+    reason: string;
+}
+/** It succeeded without calling the gate: Token ACL's idempotent instructions return early on an account already
+ * in the target state. */
+ | {
+    outcome: "skipped";
+    reason: string;
+}
+/** It failed outside the gate's decision (Token ACL, Token-2022, the system program, fees, …). */
+ | {
+    outcome: "failed";
+    program: string;
+    message: string;
+    reason: string;
+};
+/**
+ * The verdict of a thaw or freeze transaction from its logs. `succeeded` is whether it landed (or simulated) without
+ * error. `errorCode` is the custom error number of a failed instruction, when known: it recovers the gate's code if
+ * the logs were cut.
+ */
+declare function classifyGateLogs(logs: readonly string[], succeeded: boolean, action: GateAction, opts?: {
+    gateId?: string;
+    errorCode?: number;
+}): GateVerdict;
+
+export { FLAG_CODES, type FlagCode, GATE_DENY_ERRORS, type GateAction, type GateLogs, type GateVerdict, STRUCTURAL_DENY_CODES, type StructuralDenyCode, THAWGATE_GATE_ID, THAW_ALLOW_CODES, type TgCode, type ThawAllowCode, classifyGateLogs, describe, isTgCode, parseGateLogs };

package/dist/reasons.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @module gate/reasons
+ * @description ThawGate's reason codes and the one parser for them.
+ *
+ * On every thaw and freeze decision the gate logs `TG:ALLOW:<CODE>` or `TG:DENY:<CODE>`
+ * (programs/thawgate-gate/src/decision.rs). `explain()`, `freezeIfInvalid()` and the keeper all read a transaction's
+ * logs through {@link classifyGateLogs}, so a wallet's reason is computed one way everywhere.
+ *
+ * This module has no imports. Services that don't want the SDK's Solana dependencies load it on its own:
+ * `import { classifyGateLogs } from "@thawgate/sdk/reasons"`.
+ */
+/** The ThawGate gating program (devnet). The same value as `THAWGATE_GATE_PROGRAM_ID`, as a string. */
+declare const THAWGATE_GATE_ID = "THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ";
+/** Which Token ACL permissionless instruction called the gate. */
+type GateAction = "thaw" | "freeze";
+/** Why a thaw passes (`TG:ALLOW:<code>` on thaw). */
+declare const THAW_ALLOW_CODES: readonly ["KYC", "PDA_ALLOWLISTED", "ALLOWLISTED", "CLEAN"];
+/** A policy flag on the owner: `TG:DENY:<code>` on thaw, `TG:ALLOW:<code>` on freeze. */
+declare const FLAG_CODES: readonly ["BLACKLISTED", "NOT_ALLOWLISTED", "NO_CREDENTIAL", "CREDENTIAL_EXPIRED", "KYC_LEVEL_TOO_LOW"];
+/** Denied before any policy decision, on thaw and on freeze. */
+declare const STRUCTURAL_DENY_CODES: readonly ["MISSING_ACCOUNTS", "BAD_POLICY", "BAD_REGISTRY_ENTRY", "BAD_CREDENTIAL"];
+type ThawAllowCode = (typeof THAW_ALLOW_CODES)[number];
+type FlagCode = (typeof FLAG_CODES)[number];
+type StructuralDenyCode = (typeof STRUCTURAL_DENY_CODES)[number];
+/** Every code the gate logs. `NO_IMMUTABLE_OWNER` denies a thaw only; `COMPLIANT` denies a freeze only. */
+type TgCode = ThawAllowCode | FlagCode | StructuralDenyCode | "NO_IMMUTABLE_OWNER" | "COMPLIANT";
+/**
+ * The gate's custom error number for each `TG:DENY` code (errors.rs `Denied*`, 6009–6019). Used only when a
+ * simulation's logs were cut before the gate's own line.
+ */
+declare const GATE_DENY_ERRORS: Readonly<Record<number, TgCode>>;
+declare function isTgCode(code: string): code is TgCode;
+/**
+ * A human sentence for a gate decision, e.g. `describe("DENY", "NO_CREDENTIAL", "thaw")` →
+ * "Unlock denied: the owner has no SAS attestation …". The action matters: BLACKLISTED denies a thaw but allows a freeze.
+ */
+declare function describe(decision: "ALLOW" | "DENY", code: string, action: GateAction): string;
+interface GateLogs {
+    /** A frame of the gating program appears in the logs. */
+    gateInvoked: boolean;
+    /** The gate's `TG:` line: the first one inside one of its own frames. */
+    decision: {
+        kind: "ALLOW" | "DENY";
+        code: string;
+    } | null;
+    /** The first `Program <id> failed: <message>` line. */
+    failure: {
+        program: string;
+        message: string;
+    } | null;
+}
+/**
+ * Reads a transaction's (or a simulation's) logs. Only `TG:` lines logged inside the gate's own frames count, so a
+ * different gating program can't impersonate a ThawGate decision. The first match wins: the gate's `msg!` line comes
+ * before Anchor's error line, which repeats the code.
+ */
+declare function parseGateLogs(logs: readonly string[], gateId?: string): GateLogs;
+/** The gate's verdict on one thaw or freeze transaction. */
+type GateVerdict = 
+/** The gate allowed it (a thaw unlocked the account, or a freeze froze it). */
+{
+    outcome: "allowed";
+    code: string;
+    reason: string;
+}
+/** The gate denied it. On freeze, `COMPLIANT` means the owner passes the policy. */
+ | {
+    outcome: "denied";
+    code: string;
+    reason: string;
+}
+/** It succeeded without calling the gate: Token ACL's idempotent instructions return early on an account already
+ * in the target state. */
+ | {
+    outcome: "skipped";
+    reason: string;
+}
+/** It failed outside the gate's decision (Token ACL, Token-2022, the system program, fees, …). */
+ | {
+    outcome: "failed";
+    program: string;
+    message: string;
+    reason: string;
+};
+/**
+ * The verdict of a thaw or freeze transaction from its logs. `succeeded` is whether it landed (or simulated) without
+ * error. `errorCode` is the custom error number of a failed instruction, when known: it recovers the gate's code if
+ * the logs were cut.
+ */
+declare function classifyGateLogs(logs: readonly string[], succeeded: boolean, action: GateAction, opts?: {
+    gateId?: string;
+    errorCode?: number;
+}): GateVerdict;
+
+export { FLAG_CODES, type FlagCode, GATE_DENY_ERRORS, type GateAction, type GateLogs, type GateVerdict, STRUCTURAL_DENY_CODES, type StructuralDenyCode, THAWGATE_GATE_ID, THAW_ALLOW_CODES, type TgCode, type ThawAllowCode, classifyGateLogs, describe, isTgCode, parseGateLogs };

package/dist/reasons.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// src/gate/reasons.ts
+var THAWGATE_GATE_ID = "THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ";
+var THAW_ALLOW_CODES = ["KYC", "PDA_ALLOWLISTED", "ALLOWLISTED", "CLEAN"];
+var FLAG_CODES = ["BLACKLISTED", "NOT_ALLOWLISTED", "NO_CREDENTIAL", "CREDENTIAL_EXPIRED", "KYC_LEVEL_TOO_LOW"];
+var STRUCTURAL_DENY_CODES = ["MISSING_ACCOUNTS", "BAD_POLICY", "BAD_REGISTRY_ENTRY", "BAD_CREDENTIAL"];
+var FACTS = {
+  KYC: "the owner holds a live SAS attestation from the policy's credential and schema",
+  PDA_ALLOWLISTED: "the owner is a program address (PDA) on the issuer's allowlist (BypassForPdas)",
+  ALLOWLISTED: "the owner is on the issuer's allowlist",
+  CLEAN: "no policy check flags the owner",
+  BLACKLISTED: "the owner is on the issuer's blacklist",
+  NOT_ALLOWLISTED: "the policy is allowlist-only and the owner is not on the issuer's allowlist",
+  NO_CREDENTIAL: "the owner has no SAS attestation from the policy's credential and schema (never issued, or revoked)",
+  CREDENTIAL_EXPIRED: "the owner's SAS attestation has expired",
+  KYC_LEVEL_TOO_LOW: "the owner's kyc_level is below the policy minimum",
+  NO_IMMUTABLE_OWNER: "the token account lacks the ImmutableOwner extension (use an associated token account)",
+  MISSING_ACCOUNTS: "the transaction left out accounts the policy needs (resolve the gate's extra account metas)",
+  BAD_POLICY: "the policy account is not this mint's ThawGate policy",
+  BAD_REGISTRY_ENTRY: "a blacklist or allowlist account has the wrong owner, type or fields",
+  BAD_CREDENTIAL: "the account at the attestation address is not a SAS attestation of this credential, schema and owner",
+  COMPLIANT: "the owner passes the policy"
+};
+var GATE_DENY_ERRORS = {
+  6009: "MISSING_ACCOUNTS",
+  6010: "BAD_POLICY",
+  6011: "BAD_REGISTRY_ENTRY",
+  6012: "BAD_CREDENTIAL",
+  6013: "NO_IMMUTABLE_OWNER",
+  6014: "BLACKLISTED",
+  6015: "NOT_ALLOWLISTED",
+  6016: "NO_CREDENTIAL",
+  6017: "CREDENTIAL_EXPIRED",
+  6018: "KYC_LEVEL_TOO_LOW",
+  6019: "COMPLIANT"
+};
+function isTgCode(code) {
+  return Object.prototype.hasOwnProperty.call(FACTS, code);
+}
+function describe(decision, code, action) {
+  const fact = isTgCode(code) ? FACTS[code] : `the gate returned ${code}, a code this SDK version doesn't know`;
+  if (action === "thaw") return `${decision === "ALLOW" ? "Unlock allowed" : "Unlock denied"}: ${fact}.`;
+  if (decision === "ALLOW") return `Freezable by anyone: ${fact}.`;
+  return code === "COMPLIANT" ? `Not freezable: ${fact}.` : `Freeze denied: ${fact}.`;
+}
+var INVOKE = /^Program (\S+) invoke \[\d+\]$/;
+var EXIT = /^Program (\S+) (?:success|failed: .*)$/;
+var FAILED = /^Program (\S+) failed: (.*)$/;
+var TG_LINE = /^Program log: .*?TG:(ALLOW|DENY):([A-Z_]+)/;
+function parseGateLogs(logs, gateId = THAWGATE_GATE_ID) {
+  const stack = [];
+  let gateInvoked = false;
+  let decision = null;
+  let failure = null;
+  for (const line of logs) {
+    const invoke = INVOKE.exec(line);
+    if (invoke) {
+      stack.push(invoke[1]);
+      if (invoke[1] === gateId) gateInvoked = true;
+      continue;
+    }
+    const failed = FAILED.exec(line);
+    if (failed && !failure) failure = { program: failed[1], message: failed[2] };
+    if (EXIT.test(line)) {
+      stack.pop();
+      continue;
+    }
+    if (!decision && stack[stack.length - 1] === gateId) {
+      const tg = TG_LINE.exec(line);
+      if (tg) decision = { kind: tg[1], code: tg[2] };
+    }
+  }
+  return { gateInvoked, decision, failure };
+}
+function classifyGateLogs(logs, succeeded, action, opts = {}) {
+  const { gateInvoked, decision, failure } = parseGateLogs(logs, opts.gateId);
+  if (succeeded) {
+    if (!gateInvoked) {
+      const state = action === "thaw" ? "thawed" : "frozen";
+      return { outcome: "skipped", reason: `No change: the account is already ${state}, so Token ACL did not call the gate.` };
+    }
+    const code = decision?.kind === "ALLOW" ? decision.code : "UNKNOWN";
+    return { outcome: "allowed", code, reason: describe("ALLOW", code, action) };
+  }
+  if (decision?.kind === "DENY") return { outcome: "denied", code: decision.code, reason: describe("DENY", decision.code, action) };
+  const gateFailed = failure === null || failure.program === (opts.gateId ?? THAWGATE_GATE_ID);
+  const fromError = opts.errorCode !== void 0 && gateFailed ? GATE_DENY_ERRORS[opts.errorCode] : void 0;
+  if (fromError) return { outcome: "denied", code: fromError, reason: describe("DENY", fromError, action) };
+  if (failure) {
+    return {
+      outcome: "failed",
+      program: failure.program,
+      message: failure.message,
+      reason: `Failed before the gate decided: ${failure.program} returned "${failure.message}".`
+    };
+  }
+  return { outcome: "failed", program: "unknown", message: "no logs", reason: "Failed, and the logs give no reason." };
+}
+
+exports.FLAG_CODES = FLAG_CODES;
+exports.GATE_DENY_ERRORS = GATE_DENY_ERRORS;
+exports.STRUCTURAL_DENY_CODES = STRUCTURAL_DENY_CODES;
+exports.THAWGATE_GATE_ID = THAWGATE_GATE_ID;
+exports.THAW_ALLOW_CODES = THAW_ALLOW_CODES;
+exports.classifyGateLogs = classifyGateLogs;
+exports.describe = describe;
+exports.isTgCode = isTgCode;
+exports.parseGateLogs = parseGateLogs;
+//# sourceMappingURL=reasons.js.map
+//# sourceMappingURL=reasons.js.map

package/dist/reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gate/reasons.ts"],"names":[],"mappings":";;;AAaO,IAAM,gBAAA,GAAmB;AAMzB,IAAM,gBAAA,GAAmB,CAAC,KAAA,EAAO,iBAAA,EAAmB,eAAe,OAAO;AAE1E,IAAM,aAAa,CAAC,aAAA,EAAe,iBAAA,EAAmB,eAAA,EAAiB,sBAAsB,mBAAmB;AAEhH,IAAM,qBAAA,GAAwB,CAAC,kBAAA,EAAoB,YAAA,EAAc,sBAAsB,gBAAgB;AAS9G,IAAM,KAAA,GAAgC;AAAA,EAClC,GAAA,EAAK,gFAAA;AAAA,EACL,eAAA,EAAiB,gFAAA;AAAA,EACjB,WAAA,EAAa,wCAAA;AAAA,EACb,KAAA,EAAO,iCAAA;AAAA,EACP,WAAA,EAAa,wCAAA;AAAA,EACb,eAAA,EAAiB,6EAAA;AAAA,EACjB,aAAA,EAAe,qGAAA;AAAA,EACf,kBAAA,EAAoB,yCAAA;AAAA,EACpB,iBAAA,EAAmB,mDAAA;AAAA,EACnB,kBAAA,EAAoB,wFAAA;AAAA,EACpB,gBAAA,EAAkB,6FAAA;AAAA,EAClB,UAAA,EAAY,uDAAA;AAAA,EACZ,kBAAA,EAAoB,sEAAA;AAAA,EACpB,cAAA,EAAgB,sGAAA;AAAA,EAChB,SAAA,EAAW;AACf,CAAA;AAMO,IAAM,gBAAA,GAAqD;AAAA,EAC9D,IAAA,EAAM,kBAAA;AAAA,EACN,IAAA,EAAM,YAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,gBAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,aAAA;AAAA,EACN,IAAA,EAAM,iBAAA;AAAA,EACN,IAAA,EAAM,eAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,mBAAA;AAAA,EACN,IAAA,EAAM;AACV;AAEO,SAAS,SAAS,IAAA,EAA8B;AACnD,EAAA,OAAO,MAAA,CAAO,SAAA,CAAU,cAAA,CAAe,IAAA,CAAK,OAAO,IAAI,CAAA;AAC3D;AAMO,SAAS,QAAA,CAAS,QAAA,EAA4B,IAAA,EAAc,MAAA,EAA4B;AAC3F,EAAA,MAAM,IAAA,GAAO,SAAS,IAAI,CAAA,GAAI,MAAM,IAAI,CAAA,GAAI,qBAAqB,IAAI,CAAA,sCAAA,CAAA;AACrE,EAAA,IAAI,MAAA,KAAW,QAAQ,OAAO,CAAA,EAAG,aAAa,OAAA,GAAU,gBAAA,GAAmB,eAAe,CAAA,EAAA,EAAK,IAAI,CAAA,CAAA,CAAA;AACnG,EAAA,IAAI,QAAA,KAAa,OAAA,EAAS,OAAO,CAAA,qBAAA,EAAwB,IAAI,CAAA,CAAA,CAAA;AAC7D,EAAA,OAAO,SAAS,WAAA,GAAc,CAAA,eAAA,EAAkB,IAAI,CAAA,CAAA,CAAA,GAAM,kBAAkB,IAAI,CAAA,CAAA,CAAA;AACpF;AAWA,IAAM,MAAA,GAAS,gCAAA;AACf,IAAM,IAAA,GAAO,wCAAA;AACb,IAAM,MAAA,GAAS,8BAAA;AACf,IAAM,OAAA,GAAU,4CAAA;AAOT,SAAS,aAAA,CAAc,IAAA,EAAyB,MAAA,GAAiB,gBAAA,EAA4B;AAChG,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,IAAI,WAAA,GAAc,KAAA;AAClB,EAAA,IAAI,QAAA,GAAiC,IAAA;AACrC,EAAA,IAAI,OAAA,GAA+B,IAAA;AACnC,EAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACrB,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAC/B,IAAA,IAAI,MAAA,EAAQ;AACR,MAAA,KAAA,CAAM,IAAA,CAAK,MAAA,CAAO,CAAC,CAAC,CAAA;AACpB,MAAA,IAAI,MAAA,CAAO,CAAC,CAAA,KAAM,MAAA,EAAQ,WAAA,GAAc,IAAA;AACxC,MAAA;AAAA,IACJ;AACA,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAC/B,IAAA,IAAI,MAAA,IAAU,CAAC,OAAA,EAAS,OAAA,GAAU,EAAE,OAAA,EAAS,MAAA,CAAO,CAAC,CAAA,EAAG,OAAA,EAAS,MAAA,CAAO,CAAC,CAAA,EAAE;AAC3E,IAAA,IAAI,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA,EAAG;AACjB,MAAA,KAAA,CAAM,GAAA,EAAI;AACV,MAAA;AAAA,IACJ;AACA,IAAA,IAAI,CAAC,QAAA,IAAY,KAAA,CAAM,MAAM,MAAA,GAAS,CAAC,MAAM,MAAA,EAAQ;AACjD,MAAA,MAAM,EAAA,GAAK,OAAA,CAAQ,IAAA,CAAK,IAAI,CAAA;AAC5B,MAAA,IAAI,EAAA,EAAI,QAAA,GAAW,EAAE,IAAA,EAAM,EAAA,CAAG,CAAC,CAAA,EAAuB,IAAA,EAAM,EAAA,CAAG,CAAC,CAAA,EAAE;AAAA,IACtE;AAAA,EACJ;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,QAAA,EAAU,OAAA,EAAQ;AAC5C;AAmBO,SAAS,iBACZ,IAAA,EACA,SAAA,EACA,MAAA,EACA,IAAA,GAAgD,EAAC,EACtC;AACX,EAAA,MAAM,EAAE,aAAa,QAAA,EAAU,OAAA,KAAY,aAAA,CAAc,IAAA,EAAM,KAAK,MAAM,CAAA;AAC1E,EAAA,IAAI,SAAA,EAAW;AACX,IAAA,IAAI,CAAC,WAAA,EAAa;AACd,MAAA,MAAM,KAAA,GAAQ,MAAA,KAAW,MAAA,GAAS,QAAA,GAAW,QAAA;AAC7C,MAAA,OAAO,EAAE,OAAA,EAAS,SAAA,EAAW,MAAA,EAAQ,CAAA,kCAAA,EAAqC,KAAK,CAAA,qCAAA,CAAA,EAAwC;AAAA,IAC3H;AACA,IAAA,MAAM,IAAA,GAAO,QAAA,EAAU,IAAA,KAAS,OAAA,GAAU,SAAS,IAAA,GAAO,SAAA;AAC1D,IAAA,OAAO,EAAE,SAAS,SAAA,EAAW,IAAA,EAAM,QAAQ,QAAA,CAAS,OAAA,EAAS,IAAA,EAAM,MAAM,CAAA,EAAE;AAAA,EAC/E;AACA,EAAA,IAAI,UAAU,IAAA,KAAS,MAAA,EAAQ,OAAO,EAAE,SAAS,QAAA,EAAU,IAAA,EAAM,QAAA,CAAS,IAAA,EAAM,QAAQ,QAAA,CAAS,MAAA,EAAQ,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAE;AAGhI,EAAA,MAAM,aAAa,OAAA,KAAY,IAAA,IAAQ,OAAA,CAAQ,OAAA,MAAa,KAAK,MAAA,IAAU,gBAAA,CAAA;AAC3E,EAAA,MAAM,SAAA,GAAY,KAAK,SAAA,KAAc,MAAA,IAAa,aAAa,gBAAA,CAAiB,IAAA,CAAK,SAAS,CAAA,GAAI,MAAA;AAClG,EAAA,IAAI,SAAA,EAAW,OAAO,EAAE,OAAA,EAAS,QAAA,EAAU,IAAA,EAAM,SAAA,EAAW,MAAA,EAAQ,QAAA,CAAS,MAAA,EAAQ,SAAA,EAAW,MAAM,CAAA,EAAE;AACxG,EAAA,IAAI,OAAA,EAAS;AACT,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,QAAA;AAAA,MACT,SAAS,OAAA,CAAQ,OAAA;AAAA,MACjB,SAAS,OAAA,CAAQ,OAAA;AAAA,MACjB,QAAQ,CAAA,gCAAA,EAAmC,OAAA,CAAQ,OAAO,CAAA,WAAA,EAAc,QAAQ,OAAO,CAAA,EAAA;AAAA,KAC3F;AAAA,EACJ;AACA,EAAA,OAAO,EAAE,SAAS,QAAA,EAAU,OAAA,EAAS,WAAW,OAAA,EAAS,SAAA,EAAW,QAAQ,sCAAA,EAAuC;AACvH","file":"reasons.js","sourcesContent":["/**\n * @module gate/reasons\n * @description ThawGate's reason codes and the one parser for them.\n *\n * On every thaw and freeze decision the gate logs `TG:ALLOW:<CODE>` or `TG:DENY:<CODE>`\n * (programs/thawgate-gate/src/decision.rs). `explain()`, `freezeIfInvalid()` and the keeper all read a transaction's\n * logs through {@link classifyGateLogs}, so a wallet's reason is computed one way everywhere.\n *\n * This module has no imports. Services that don't want the SDK's Solana dependencies load it on its own:\n * `import { classifyGateLogs } from \"@thawgate/sdk/reasons\"`.\n */\n\n/** The ThawGate gating program (devnet). The same value as `THAWGATE_GATE_PROGRAM_ID`, as a string. */\nexport const THAWGATE_GATE_ID = \"THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ\";\n\n/** Which Token ACL permissionless instruction called the gate. */\nexport type GateAction = \"thaw\" | \"freeze\";\n\n/** Why a thaw passes (`TG:ALLOW:<code>` on thaw). */\nexport const THAW_ALLOW_CODES = [\"KYC\", \"PDA_ALLOWLISTED\", \"ALLOWLISTED\", \"CLEAN\"] as const;\n/** A policy flag on the owner: `TG:DENY:<code>` on thaw, `TG:ALLOW:<code>` on freeze. */\nexport const FLAG_CODES = [\"BLACKLISTED\", \"NOT_ALLOWLISTED\", \"NO_CREDENTIAL\", \"CREDENTIAL_EXPIRED\", \"KYC_LEVEL_TOO_LOW\"] as const;\n/** Denied before any policy decision, on thaw and on freeze. */\nexport const STRUCTURAL_DENY_CODES = [\"MISSING_ACCOUNTS\", \"BAD_POLICY\", \"BAD_REGISTRY_ENTRY\", \"BAD_CREDENTIAL\"] as const;\n\nexport type ThawAllowCode = (typeof THAW_ALLOW_CODES)[number];\nexport type FlagCode = (typeof FLAG_CODES)[number];\nexport type StructuralDenyCode = (typeof STRUCTURAL_DENY_CODES)[number];\n/** Every code the gate logs. `NO_IMMUTABLE_OWNER` denies a thaw only; `COMPLIANT` denies a freeze only. */\nexport type TgCode = ThawAllowCode | FlagCode | StructuralDenyCode | \"NO_IMMUTABLE_OWNER\" | \"COMPLIANT\";\n\n/** What each code says about the owner, as the second half of a sentence. */\nconst FACTS: Record<TgCode, string> = {\n    KYC: \"the owner holds a live SAS attestation from the policy's credential and schema\",\n    PDA_ALLOWLISTED: \"the owner is a program address (PDA) on the issuer's allowlist (BypassForPdas)\",\n    ALLOWLISTED: \"the owner is on the issuer's allowlist\",\n    CLEAN: \"no policy check flags the owner\",\n    BLACKLISTED: \"the owner is on the issuer's blacklist\",\n    NOT_ALLOWLISTED: \"the policy is allowlist-only and the owner is not on the issuer's allowlist\",\n    NO_CREDENTIAL: \"the owner has no SAS attestation from the policy's credential and schema (never issued, or revoked)\",\n    CREDENTIAL_EXPIRED: \"the owner's SAS attestation has expired\",\n    KYC_LEVEL_TOO_LOW: \"the owner's kyc_level is below the policy minimum\",\n    NO_IMMUTABLE_OWNER: \"the token account lacks the ImmutableOwner extension (use an associated token account)\",\n    MISSING_ACCOUNTS: \"the transaction left out accounts the policy needs (resolve the gate's extra account metas)\",\n    BAD_POLICY: \"the policy account is not this mint's ThawGate policy\",\n    BAD_REGISTRY_ENTRY: \"a blacklist or allowlist account has the wrong owner, type or fields\",\n    BAD_CREDENTIAL: \"the account at the attestation address is not a SAS attestation of this credential, schema and owner\",\n    COMPLIANT: \"the owner passes the policy\",\n};\n\n/**\n * The gate's custom error number for each `TG:DENY` code (errors.rs `Denied*`, 6009–6019). Used only when a\n * simulation's logs were cut before the gate's own line.\n */\nexport const GATE_DENY_ERRORS: Readonly<Record<number, TgCode>> = {\n    6009: \"MISSING_ACCOUNTS\",\n    6010: \"BAD_POLICY\",\n    6011: \"BAD_REGISTRY_ENTRY\",\n    6012: \"BAD_CREDENTIAL\",\n    6013: \"NO_IMMUTABLE_OWNER\",\n    6014: \"BLACKLISTED\",\n    6015: \"NOT_ALLOWLISTED\",\n    6016: \"NO_CREDENTIAL\",\n    6017: \"CREDENTIAL_EXPIRED\",\n    6018: \"KYC_LEVEL_TOO_LOW\",\n    6019: \"COMPLIANT\",\n};\n\nexport function isTgCode(code: string): code is TgCode {\n    return Object.prototype.hasOwnProperty.call(FACTS, code);\n}\n\n/**\n * A human sentence for a gate decision, e.g. `describe(\"DENY\", \"NO_CREDENTIAL\", \"thaw\")` →\n * \"Unlock denied: the owner has no SAS attestation …\". The action matters: BLACKLISTED denies a thaw but allows a freeze.\n */\nexport function describe(decision: \"ALLOW\" | \"DENY\", code: string, action: GateAction): string {\n    const fact = isTgCode(code) ? FACTS[code] : `the gate returned ${code}, a code this SDK version doesn't know`;\n    if (action === \"thaw\") return `${decision === \"ALLOW\" ? \"Unlock allowed\" : \"Unlock denied\"}: ${fact}.`;\n    if (decision === \"ALLOW\") return `Freezable by anyone: ${fact}.`;\n    return code === \"COMPLIANT\" ? `Not freezable: ${fact}.` : `Freeze denied: ${fact}.`;\n}\n\nexport interface GateLogs {\n    /** A frame of the gating program appears in the logs. */\n    gateInvoked: boolean;\n    /** The gate's `TG:` line: the first one inside one of its own frames. */\n    decision: { kind: \"ALLOW\" | \"DENY\"; code: string } | null;\n    /** The first `Program <id> failed: <message>` line. */\n    failure: { program: string; message: string } | null;\n}\n\nconst INVOKE = /^Program (\\S+) invoke \\[\\d+\\]$/;\nconst EXIT = /^Program (\\S+) (?:success|failed: .*)$/;\nconst FAILED = /^Program (\\S+) failed: (.*)$/;\nconst TG_LINE = /^Program log: .*?TG:(ALLOW|DENY):([A-Z_]+)/;\n\n/**\n * Reads a transaction's (or a simulation's) logs. Only `TG:` lines logged inside the gate's own frames count, so a\n * different gating program can't impersonate a ThawGate decision. The first match wins: the gate's `msg!` line comes\n * before Anchor's error line, which repeats the code.\n */\nexport function parseGateLogs(logs: readonly string[], gateId: string = THAWGATE_GATE_ID): GateLogs {\n    const stack: string[] = [];\n    let gateInvoked = false;\n    let decision: GateLogs[\"decision\"] = null;\n    let failure: GateLogs[\"failure\"] = null;\n    for (const line of logs) {\n        const invoke = INVOKE.exec(line);\n        if (invoke) {\n            stack.push(invoke[1]);\n            if (invoke[1] === gateId) gateInvoked = true;\n            continue;\n        }\n        const failed = FAILED.exec(line);\n        if (failed && !failure) failure = { program: failed[1], message: failed[2] };\n        if (EXIT.test(line)) {\n            stack.pop();\n            continue;\n        }\n        if (!decision && stack[stack.length - 1] === gateId) {\n            const tg = TG_LINE.exec(line);\n            if (tg) decision = { kind: tg[1] as \"ALLOW\" | \"DENY\", code: tg[2] };\n        }\n    }\n    return { gateInvoked, decision, failure };\n}\n\n/** The gate's verdict on one thaw or freeze transaction. */\nexport type GateVerdict =\n    /** The gate allowed it (a thaw unlocked the account, or a freeze froze it). */\n    | { outcome: \"allowed\"; code: string; reason: string }\n    /** The gate denied it. On freeze, `COMPLIANT` means the owner passes the policy. */\n    | { outcome: \"denied\"; code: string; reason: string }\n    /** It succeeded without calling the gate: Token ACL's idempotent instructions return early on an account already\n     * in the target state. */\n    | { outcome: \"skipped\"; reason: string }\n    /** It failed outside the gate's decision (Token ACL, Token-2022, the system program, fees, …). */\n    | { outcome: \"failed\"; program: string; message: string; reason: string };\n\n/**\n * The verdict of a thaw or freeze transaction from its logs. `succeeded` is whether it landed (or simulated) without\n * error. `errorCode` is the custom error number of a failed instruction, when known: it recovers the gate's code if\n * the logs were cut.\n */\nexport function classifyGateLogs(\n    logs: readonly string[],\n    succeeded: boolean,\n    action: GateAction,\n    opts: { gateId?: string; errorCode?: number } = {},\n): GateVerdict {\n    const { gateInvoked, decision, failure } = parseGateLogs(logs, opts.gateId);\n    if (succeeded) {\n        if (!gateInvoked) {\n            const state = action === \"thaw\" ? \"thawed\" : \"frozen\";\n            return { outcome: \"skipped\", reason: `No change: the account is already ${state}, so Token ACL did not call the gate.` };\n        }\n        const code = decision?.kind === \"ALLOW\" ? decision.code : \"UNKNOWN\";\n        return { outcome: \"allowed\", code, reason: describe(\"ALLOW\", code, action) };\n    }\n    if (decision?.kind === \"DENY\") return { outcome: \"denied\", code: decision.code, reason: describe(\"DENY\", decision.code, action) };\n    // Truncated logs (\"Log truncated\") usually lose the gate's own failed line too, so accept a missing failure line.\n    // 6009–6019 don't collide with Token ACL's or Token-2022's error numbers, which are small.\n    const gateFailed = failure === null || failure.program === (opts.gateId ?? THAWGATE_GATE_ID);\n    const fromError = opts.errorCode !== undefined && gateFailed ? GATE_DENY_ERRORS[opts.errorCode] : undefined;\n    if (fromError) return { outcome: \"denied\", code: fromError, reason: describe(\"DENY\", fromError, action) };\n    if (failure) {\n        return {\n            outcome: \"failed\",\n            program: failure.program,\n            message: failure.message,\n            reason: `Failed before the gate decided: ${failure.program} returned \"${failure.message}\".`,\n        };\n    }\n    return { outcome: \"failed\", program: \"unknown\", message: \"no logs\", reason: \"Failed, and the logs give no reason.\" };\n}\n"]}

package/dist/reasons.mjs

@@ -0,0 +1,101 @@
+// src/gate/reasons.ts
+var THAWGATE_GATE_ID = "THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ";
+var THAW_ALLOW_CODES = ["KYC", "PDA_ALLOWLISTED", "ALLOWLISTED", "CLEAN"];
+var FLAG_CODES = ["BLACKLISTED", "NOT_ALLOWLISTED", "NO_CREDENTIAL", "CREDENTIAL_EXPIRED", "KYC_LEVEL_TOO_LOW"];
+var STRUCTURAL_DENY_CODES = ["MISSING_ACCOUNTS", "BAD_POLICY", "BAD_REGISTRY_ENTRY", "BAD_CREDENTIAL"];
+var FACTS = {
+  KYC: "the owner holds a live SAS attestation from the policy's credential and schema",
+  PDA_ALLOWLISTED: "the owner is a program address (PDA) on the issuer's allowlist (BypassForPdas)",
+  ALLOWLISTED: "the owner is on the issuer's allowlist",
+  CLEAN: "no policy check flags the owner",
+  BLACKLISTED: "the owner is on the issuer's blacklist",
+  NOT_ALLOWLISTED: "the policy is allowlist-only and the owner is not on the issuer's allowlist",
+  NO_CREDENTIAL: "the owner has no SAS attestation from the policy's credential and schema (never issued, or revoked)",
+  CREDENTIAL_EXPIRED: "the owner's SAS attestation has expired",
+  KYC_LEVEL_TOO_LOW: "the owner's kyc_level is below the policy minimum",
+  NO_IMMUTABLE_OWNER: "the token account lacks the ImmutableOwner extension (use an associated token account)",
+  MISSING_ACCOUNTS: "the transaction left out accounts the policy needs (resolve the gate's extra account metas)",
+  BAD_POLICY: "the policy account is not this mint's ThawGate policy",
+  BAD_REGISTRY_ENTRY: "a blacklist or allowlist account has the wrong owner, type or fields",
+  BAD_CREDENTIAL: "the account at the attestation address is not a SAS attestation of this credential, schema and owner",
+  COMPLIANT: "the owner passes the policy"
+};
+var GATE_DENY_ERRORS = {
+  6009: "MISSING_ACCOUNTS",
+  6010: "BAD_POLICY",
+  6011: "BAD_REGISTRY_ENTRY",
+  6012: "BAD_CREDENTIAL",
+  6013: "NO_IMMUTABLE_OWNER",
+  6014: "BLACKLISTED",
+  6015: "NOT_ALLOWLISTED",
+  6016: "NO_CREDENTIAL",
+  6017: "CREDENTIAL_EXPIRED",
+  6018: "KYC_LEVEL_TOO_LOW",
+  6019: "COMPLIANT"
+};
+function isTgCode(code) {
+  return Object.prototype.hasOwnProperty.call(FACTS, code);
+}
+function describe(decision, code, action) {
+  const fact = isTgCode(code) ? FACTS[code] : `the gate returned ${code}, a code this SDK version doesn't know`;
+  if (action === "thaw") return `${decision === "ALLOW" ? "Unlock allowed" : "Unlock denied"}: ${fact}.`;
+  if (decision === "ALLOW") return `Freezable by anyone: ${fact}.`;
+  return code === "COMPLIANT" ? `Not freezable: ${fact}.` : `Freeze denied: ${fact}.`;
+}
+var INVOKE = /^Program (\S+) invoke \[\d+\]$/;
+var EXIT = /^Program (\S+) (?:success|failed: .*)$/;
+var FAILED = /^Program (\S+) failed: (.*)$/;
+var TG_LINE = /^Program log: .*?TG:(ALLOW|DENY):([A-Z_]+)/;
+function parseGateLogs(logs, gateId = THAWGATE_GATE_ID) {
+  const stack = [];
+  let gateInvoked = false;
+  let decision = null;
+  let failure = null;
+  for (const line of logs) {
+    const invoke = INVOKE.exec(line);
+    if (invoke) {
+      stack.push(invoke[1]);
+      if (invoke[1] === gateId) gateInvoked = true;
+      continue;
+    }
+    const failed = FAILED.exec(line);
+    if (failed && !failure) failure = { program: failed[1], message: failed[2] };
+    if (EXIT.test(line)) {
+      stack.pop();
+      continue;
+    }
+    if (!decision && stack[stack.length - 1] === gateId) {
+      const tg = TG_LINE.exec(line);
+      if (tg) decision = { kind: tg[1], code: tg[2] };
+    }
+  }
+  return { gateInvoked, decision, failure };
+}
+function classifyGateLogs(logs, succeeded, action, opts = {}) {
+  const { gateInvoked, decision, failure } = parseGateLogs(logs, opts.gateId);
+  if (succeeded) {
+    if (!gateInvoked) {
+      const state = action === "thaw" ? "thawed" : "frozen";
+      return { outcome: "skipped", reason: `No change: the account is already ${state}, so Token ACL did not call the gate.` };
+    }
+    const code = decision?.kind === "ALLOW" ? decision.code : "UNKNOWN";
+    return { outcome: "allowed", code, reason: describe("ALLOW", code, action) };
+  }
+  if (decision?.kind === "DENY") return { outcome: "denied", code: decision.code, reason: describe("DENY", decision.code, action) };
+  const gateFailed = failure === null || failure.program === (opts.gateId ?? THAWGATE_GATE_ID);
+  const fromError = opts.errorCode !== void 0 && gateFailed ? GATE_DENY_ERRORS[opts.errorCode] : void 0;
+  if (fromError) return { outcome: "denied", code: fromError, reason: describe("DENY", fromError, action) };
+  if (failure) {
+    return {
+      outcome: "failed",
+      program: failure.program,
+      message: failure.message,
+      reason: `Failed before the gate decided: ${failure.program} returned "${failure.message}".`
+    };
+  }
+  return { outcome: "failed", program: "unknown", message: "no logs", reason: "Failed, and the logs give no reason." };
+}
+
+export { FLAG_CODES, GATE_DENY_ERRORS, STRUCTURAL_DENY_CODES, THAWGATE_GATE_ID, THAW_ALLOW_CODES, classifyGateLogs, describe, isTgCode, parseGateLogs };
+//# sourceMappingURL=reasons.mjs.map
+//# sourceMappingURL=reasons.mjs.map

package/dist/reasons.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gate/reasons.ts"],"names":[],"mappings":";AAaO,IAAM,gBAAA,GAAmB;AAMzB,IAAM,gBAAA,GAAmB,CAAC,KAAA,EAAO,iBAAA,EAAmB,eAAe,OAAO;AAE1E,IAAM,aAAa,CAAC,aAAA,EAAe,iBAAA,EAAmB,eAAA,EAAiB,sBAAsB,mBAAmB;AAEhH,IAAM,qBAAA,GAAwB,CAAC,kBAAA,EAAoB,YAAA,EAAc,sBAAsB,gBAAgB;AAS9G,IAAM,KAAA,GAAgC;AAAA,EAClC,GAAA,EAAK,gFAAA;AAAA,EACL,eAAA,EAAiB,gFAAA;AAAA,EACjB,WAAA,EAAa,wCAAA;AAAA,EACb,KAAA,EAAO,iCAAA;AAAA,EACP,WAAA,EAAa,wCAAA;AAAA,EACb,eAAA,EAAiB,6EAAA;AAAA,EACjB,aAAA,EAAe,qGAAA;AAAA,EACf,kBAAA,EAAoB,yCAAA;AAAA,EACpB,iBAAA,EAAmB,mDAAA;AAAA,EACnB,kBAAA,EAAoB,wFAAA;AAAA,EACpB,gBAAA,EAAkB,6FAAA;AAAA,EAClB,UAAA,EAAY,uDAAA;AAAA,EACZ,kBAAA,EAAoB,sEAAA;AAAA,EACpB,cAAA,EAAgB,sGAAA;AAAA,EAChB,SAAA,EAAW;AACf,CAAA;AAMO,IAAM,gBAAA,GAAqD;AAAA,EAC9D,IAAA,EAAM,kBAAA;AAAA,EACN,IAAA,EAAM,YAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,gBAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,aAAA;AAAA,EACN,IAAA,EAAM,iBAAA;AAAA,EACN,IAAA,EAAM,eAAA;AAAA,EACN,IAAA,EAAM,oBAAA;AAAA,EACN,IAAA,EAAM,mBAAA;AAAA,EACN,IAAA,EAAM;AACV;AAEO,SAAS,SAAS,IAAA,EAA8B;AACnD,EAAA,OAAO,MAAA,CAAO,SAAA,CAAU,cAAA,CAAe,IAAA,CAAK,OAAO,IAAI,CAAA;AAC3D;AAMO,SAAS,QAAA,CAAS,QAAA,EAA4B,IAAA,EAAc,MAAA,EAA4B;AAC3F,EAAA,MAAM,IAAA,GAAO,SAAS,IAAI,CAAA,GAAI,MAAM,IAAI,CAAA,GAAI,qBAAqB,IAAI,CAAA,sCAAA,CAAA;AACrE,EAAA,IAAI,MAAA,KAAW,QAAQ,OAAO,CAAA,EAAG,aAAa,OAAA,GAAU,gBAAA,GAAmB,eAAe,CAAA,EAAA,EAAK,IAAI,CAAA,CAAA,CAAA;AACnG,EAAA,IAAI,QAAA,KAAa,OAAA,EAAS,OAAO,CAAA,qBAAA,EAAwB,IAAI,CAAA,CAAA,CAAA;AAC7D,EAAA,OAAO,SAAS,WAAA,GAAc,CAAA,eAAA,EAAkB,IAAI,CAAA,CAAA,CAAA,GAAM,kBAAkB,IAAI,CAAA,CAAA,CAAA;AACpF;AAWA,IAAM,MAAA,GAAS,gCAAA;AACf,IAAM,IAAA,GAAO,wCAAA;AACb,IAAM,MAAA,GAAS,8BAAA;AACf,IAAM,OAAA,GAAU,4CAAA;AAOT,SAAS,aAAA,CAAc,IAAA,EAAyB,MAAA,GAAiB,gBAAA,EAA4B;AAChG,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,IAAI,WAAA,GAAc,KAAA;AAClB,EAAA,IAAI,QAAA,GAAiC,IAAA;AACrC,EAAA,IAAI,OAAA,GAA+B,IAAA;AACnC,EAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACrB,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAC/B,IAAA,IAAI,MAAA,EAAQ;AACR,MAAA,KAAA,CAAM,IAAA,CAAK,MAAA,CAAO,CAAC,CAAC,CAAA;AACpB,MAAA,IAAI,MAAA,CAAO,CAAC,CAAA,KAAM,MAAA,EAAQ,WAAA,GAAc,IAAA;AACxC,MAAA;AAAA,IACJ;AACA,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAC/B,IAAA,IAAI,MAAA,IAAU,CAAC,OAAA,EAAS,OAAA,GAAU,EAAE,OAAA,EAAS,MAAA,CAAO,CAAC,CAAA,EAAG,OAAA,EAAS,MAAA,CAAO,CAAC,CAAA,EAAE;AAC3E,IAAA,IAAI,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA,EAAG;AACjB,MAAA,KAAA,CAAM,GAAA,EAAI;AACV,MAAA;AAAA,IACJ;AACA,IAAA,IAAI,CAAC,QAAA,IAAY,KAAA,CAAM,MAAM,MAAA,GAAS,CAAC,MAAM,MAAA,EAAQ;AACjD,MAAA,MAAM,EAAA,GAAK,OAAA,CAAQ,IAAA,CAAK,IAAI,CAAA;AAC5B,MAAA,IAAI,EAAA,EAAI,QAAA,GAAW,EAAE,IAAA,EAAM,EAAA,CAAG,CAAC,CAAA,EAAuB,IAAA,EAAM,EAAA,CAAG,CAAC,CAAA,EAAE;AAAA,IACtE;AAAA,EACJ;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,QAAA,EAAU,OAAA,EAAQ;AAC5C;AAmBO,SAAS,iBACZ,IAAA,EACA,SAAA,EACA,MAAA,EACA,IAAA,GAAgD,EAAC,EACtC;AACX,EAAA,MAAM,EAAE,aAAa,QAAA,EAAU,OAAA,KAAY,aAAA,CAAc,IAAA,EAAM,KAAK,MAAM,CAAA;AAC1E,EAAA,IAAI,SAAA,EAAW;AACX,IAAA,IAAI,CAAC,WAAA,EAAa;AACd,MAAA,MAAM,KAAA,GAAQ,MAAA,KAAW,MAAA,GAAS,QAAA,GAAW,QAAA;AAC7C,MAAA,OAAO,EAAE,OAAA,EAAS,SAAA,EAAW,MAAA,EAAQ,CAAA,kCAAA,EAAqC,KAAK,CAAA,qCAAA,CAAA,EAAwC;AAAA,IAC3H;AACA,IAAA,MAAM,IAAA,GAAO,QAAA,EAAU,IAAA,KAAS,OAAA,GAAU,SAAS,IAAA,GAAO,SAAA;AAC1D,IAAA,OAAO,EAAE,SAAS,SAAA,EAAW,IAAA,EAAM,QAAQ,QAAA,CAAS,OAAA,EAAS,IAAA,EAAM,MAAM,CAAA,EAAE;AAAA,EAC/E;AACA,EAAA,IAAI,UAAU,IAAA,KAAS,MAAA,EAAQ,OAAO,EAAE,SAAS,QAAA,EAAU,IAAA,EAAM,QAAA,CAAS,IAAA,EAAM,QAAQ,QAAA,CAAS,MAAA,EAAQ,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAE;AAGhI,EAAA,MAAM,aAAa,OAAA,KAAY,IAAA,IAAQ,OAAA,CAAQ,OAAA,MAAa,KAAK,MAAA,IAAU,gBAAA,CAAA;AAC3E,EAAA,MAAM,SAAA,GAAY,KAAK,SAAA,KAAc,MAAA,IAAa,aAAa,gBAAA,CAAiB,IAAA,CAAK,SAAS,CAAA,GAAI,MAAA;AAClG,EAAA,IAAI,SAAA,EAAW,OAAO,EAAE,OAAA,EAAS,QAAA,EAAU,IAAA,EAAM,SAAA,EAAW,MAAA,EAAQ,QAAA,CAAS,MAAA,EAAQ,SAAA,EAAW,MAAM,CAAA,EAAE;AACxG,EAAA,IAAI,OAAA,EAAS;AACT,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,QAAA;AAAA,MACT,SAAS,OAAA,CAAQ,OAAA;AAAA,MACjB,SAAS,OAAA,CAAQ,OAAA;AAAA,MACjB,QAAQ,CAAA,gCAAA,EAAmC,OAAA,CAAQ,OAAO,CAAA,WAAA,EAAc,QAAQ,OAAO,CAAA,EAAA;AAAA,KAC3F;AAAA,EACJ;AACA,EAAA,OAAO,EAAE,SAAS,QAAA,EAAU,OAAA,EAAS,WAAW,OAAA,EAAS,SAAA,EAAW,QAAQ,sCAAA,EAAuC;AACvH","file":"reasons.mjs","sourcesContent":["/**\n * @module gate/reasons\n * @description ThawGate's reason codes and the one parser for them.\n *\n * On every thaw and freeze decision the gate logs `TG:ALLOW:<CODE>` or `TG:DENY:<CODE>`\n * (programs/thawgate-gate/src/decision.rs). `explain()`, `freezeIfInvalid()` and the keeper all read a transaction's\n * logs through {@link classifyGateLogs}, so a wallet's reason is computed one way everywhere.\n *\n * This module has no imports. Services that don't want the SDK's Solana dependencies load it on its own:\n * `import { classifyGateLogs } from \"@thawgate/sdk/reasons\"`.\n */\n\n/** The ThawGate gating program (devnet). The same value as `THAWGATE_GATE_PROGRAM_ID`, as a string. */\nexport const THAWGATE_GATE_ID = \"THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ\";\n\n/** Which Token ACL permissionless instruction called the gate. */\nexport type GateAction = \"thaw\" | \"freeze\";\n\n/** Why a thaw passes (`TG:ALLOW:<code>` on thaw). */\nexport const THAW_ALLOW_CODES = [\"KYC\", \"PDA_ALLOWLISTED\", \"ALLOWLISTED\", \"CLEAN\"] as const;\n/** A policy flag on the owner: `TG:DENY:<code>` on thaw, `TG:ALLOW:<code>` on freeze. */\nexport const FLAG_CODES = [\"BLACKLISTED\", \"NOT_ALLOWLISTED\", \"NO_CREDENTIAL\", \"CREDENTIAL_EXPIRED\", \"KYC_LEVEL_TOO_LOW\"] as const;\n/** Denied before any policy decision, on thaw and on freeze. */\nexport const STRUCTURAL_DENY_CODES = [\"MISSING_ACCOUNTS\", \"BAD_POLICY\", \"BAD_REGISTRY_ENTRY\", \"BAD_CREDENTIAL\"] as const;\n\nexport type ThawAllowCode = (typeof THAW_ALLOW_CODES)[number];\nexport type FlagCode = (typeof FLAG_CODES)[number];\nexport type StructuralDenyCode = (typeof STRUCTURAL_DENY_CODES)[number];\n/** Every code the gate logs. `NO_IMMUTABLE_OWNER` denies a thaw only; `COMPLIANT` denies a freeze only. */\nexport type TgCode = ThawAllowCode | FlagCode | StructuralDenyCode | \"NO_IMMUTABLE_OWNER\" | \"COMPLIANT\";\n\n/** What each code says about the owner, as the second half of a sentence. */\nconst FACTS: Record<TgCode, string> = {\n    KYC: \"the owner holds a live SAS attestation from the policy's credential and schema\",\n    PDA_ALLOWLISTED: \"the owner is a program address (PDA) on the issuer's allowlist (BypassForPdas)\",\n    ALLOWLISTED: \"the owner is on the issuer's allowlist\",\n    CLEAN: \"no policy check flags the owner\",\n    BLACKLISTED: \"the owner is on the issuer's blacklist\",\n    NOT_ALLOWLISTED: \"the policy is allowlist-only and the owner is not on the issuer's allowlist\",\n    NO_CREDENTIAL: \"the owner has no SAS attestation from the policy's credential and schema (never issued, or revoked)\",\n    CREDENTIAL_EXPIRED: \"the owner's SAS attestation has expired\",\n    KYC_LEVEL_TOO_LOW: \"the owner's kyc_level is below the policy minimum\",\n    NO_IMMUTABLE_OWNER: \"the token account lacks the ImmutableOwner extension (use an associated token account)\",\n    MISSING_ACCOUNTS: \"the transaction left out accounts the policy needs (resolve the gate's extra account metas)\",\n    BAD_POLICY: \"the policy account is not this mint's ThawGate policy\",\n    BAD_REGISTRY_ENTRY: \"a blacklist or allowlist account has the wrong owner, type or fields\",\n    BAD_CREDENTIAL: \"the account at the attestation address is not a SAS attestation of this credential, schema and owner\",\n    COMPLIANT: \"the owner passes the policy\",\n};\n\n/**\n * The gate's custom error number for each `TG:DENY` code (errors.rs `Denied*`, 6009–6019). Used only when a\n * simulation's logs were cut before the gate's own line.\n */\nexport const GATE_DENY_ERRORS: Readonly<Record<number, TgCode>> = {\n    6009: \"MISSING_ACCOUNTS\",\n    6010: \"BAD_POLICY\",\n    6011: \"BAD_REGISTRY_ENTRY\",\n    6012: \"BAD_CREDENTIAL\",\n    6013: \"NO_IMMUTABLE_OWNER\",\n    6014: \"BLACKLISTED\",\n    6015: \"NOT_ALLOWLISTED\",\n    6016: \"NO_CREDENTIAL\",\n    6017: \"CREDENTIAL_EXPIRED\",\n    6018: \"KYC_LEVEL_TOO_LOW\",\n    6019: \"COMPLIANT\",\n};\n\nexport function isTgCode(code: string): code is TgCode {\n    return Object.prototype.hasOwnProperty.call(FACTS, code);\n}\n\n/**\n * A human sentence for a gate decision, e.g. `describe(\"DENY\", \"NO_CREDENTIAL\", \"thaw\")` →\n * \"Unlock denied: the owner has no SAS attestation …\". The action matters: BLACKLISTED denies a thaw but allows a freeze.\n */\nexport function describe(decision: \"ALLOW\" | \"DENY\", code: string, action: GateAction): string {\n    const fact = isTgCode(code) ? FACTS[code] : `the gate returned ${code}, a code this SDK version doesn't know`;\n    if (action === \"thaw\") return `${decision === \"ALLOW\" ? \"Unlock allowed\" : \"Unlock denied\"}: ${fact}.`;\n    if (decision === \"ALLOW\") return `Freezable by anyone: ${fact}.`;\n    return code === \"COMPLIANT\" ? `Not freezable: ${fact}.` : `Freeze denied: ${fact}.`;\n}\n\nexport interface GateLogs {\n    /** A frame of the gating program appears in the logs. */\n    gateInvoked: boolean;\n    /** The gate's `TG:` line: the first one inside one of its own frames. */\n    decision: { kind: \"ALLOW\" | \"DENY\"; code: string } | null;\n    /** The first `Program <id> failed: <message>` line. */\n    failure: { program: string; message: string } | null;\n}\n\nconst INVOKE = /^Program (\\S+) invoke \\[\\d+\\]$/;\nconst EXIT = /^Program (\\S+) (?:success|failed: .*)$/;\nconst FAILED = /^Program (\\S+) failed: (.*)$/;\nconst TG_LINE = /^Program log: .*?TG:(ALLOW|DENY):([A-Z_]+)/;\n\n/**\n * Reads a transaction's (or a simulation's) logs. Only `TG:` lines logged inside the gate's own frames count, so a\n * different gating program can't impersonate a ThawGate decision. The first match wins: the gate's `msg!` line comes\n * before Anchor's error line, which repeats the code.\n */\nexport function parseGateLogs(logs: readonly string[], gateId: string = THAWGATE_GATE_ID): GateLogs {\n    const stack: string[] = [];\n    let gateInvoked = false;\n    let decision: GateLogs[\"decision\"] = null;\n    let failure: GateLogs[\"failure\"] = null;\n    for (const line of logs) {\n        const invoke = INVOKE.exec(line);\n        if (invoke) {\n            stack.push(invoke[1]);\n            if (invoke[1] === gateId) gateInvoked = true;\n            continue;\n        }\n        const failed = FAILED.exec(line);\n        if (failed && !failure) failure = { program: failed[1], message: failed[2] };\n        if (EXIT.test(line)) {\n            stack.pop();\n            continue;\n        }\n        if (!decision && stack[stack.length - 1] === gateId) {\n            const tg = TG_LINE.exec(line);\n            if (tg) decision = { kind: tg[1] as \"ALLOW\" | \"DENY\", code: tg[2] };\n        }\n    }\n    return { gateInvoked, decision, failure };\n}\n\n/** The gate's verdict on one thaw or freeze transaction. */\nexport type GateVerdict =\n    /** The gate allowed it (a thaw unlocked the account, or a freeze froze it). */\n    | { outcome: \"allowed\"; code: string; reason: string }\n    /** The gate denied it. On freeze, `COMPLIANT` means the owner passes the policy. */\n    | { outcome: \"denied\"; code: string; reason: string }\n    /** It succeeded without calling the gate: Token ACL's idempotent instructions return early on an account already\n     * in the target state. */\n    | { outcome: \"skipped\"; reason: string }\n    /** It failed outside the gate's decision (Token ACL, Token-2022, the system program, fees, …). */\n    | { outcome: \"failed\"; program: string; message: string; reason: string };\n\n/**\n * The verdict of a thaw or freeze transaction from its logs. `succeeded` is whether it landed (or simulated) without\n * error. `errorCode` is the custom error number of a failed instruction, when known: it recovers the gate's code if\n * the logs were cut.\n */\nexport function classifyGateLogs(\n    logs: readonly string[],\n    succeeded: boolean,\n    action: GateAction,\n    opts: { gateId?: string; errorCode?: number } = {},\n): GateVerdict {\n    const { gateInvoked, decision, failure } = parseGateLogs(logs, opts.gateId);\n    if (succeeded) {\n        if (!gateInvoked) {\n            const state = action === \"thaw\" ? \"thawed\" : \"frozen\";\n            return { outcome: \"skipped\", reason: `No change: the account is already ${state}, so Token ACL did not call the gate.` };\n        }\n        const code = decision?.kind === \"ALLOW\" ? decision.code : \"UNKNOWN\";\n        return { outcome: \"allowed\", code, reason: describe(\"ALLOW\", code, action) };\n    }\n    if (decision?.kind === \"DENY\") return { outcome: \"denied\", code: decision.code, reason: describe(\"DENY\", decision.code, action) };\n    // Truncated logs (\"Log truncated\") usually lose the gate's own failed line too, so accept a missing failure line.\n    // 6009–6019 don't collide with Token ACL's or Token-2022's error numbers, which are small.\n    const gateFailed = failure === null || failure.program === (opts.gateId ?? THAWGATE_GATE_ID);\n    const fromError = opts.errorCode !== undefined && gateFailed ? GATE_DENY_ERRORS[opts.errorCode] : undefined;\n    if (fromError) return { outcome: \"denied\", code: fromError, reason: describe(\"DENY\", fromError, action) };\n    if (failure) {\n        return {\n            outcome: \"failed\",\n            program: failure.program,\n            message: failure.message,\n            reason: `Failed before the gate decided: ${failure.program} returned \"${failure.message}\".`,\n        };\n    }\n    return { outcome: \"failed\", program: \"unknown\", message: \"no logs\", reason: \"Failed, and the logs give no reason.\" };\n}\n"]}

package/package.json

@@ -1,6 +1,86 @@
 {
-  "name": "@thawgate/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@thawgate/sdk",
+    "version": "0.1.0",
+    "description": "TypeScript SDK for ThawGate: Token ACL gate policies, SSS-ACL stablecoins, SAS credentials",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/AryaSingh22/thawgate.git",
+        "directory": "sdk"
+    },
+    "homepage": "https://github.com/AryaSingh22/thawgate#readme",
+    "bugs": {
+        "url": "https://github.com/AryaSingh22/thawgate/issues"
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            },
+            "require": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        },
+        "./reasons": {
+            "import": {
+                "types": "./dist/reasons.d.mts",
+                "default": "./dist/reasons.mjs"
+            },
+            "require": {
+                "types": "./dist/reasons.d.ts",
+                "default": "./dist/reasons.js"
+            }
+        },
+        "./package.json": "./package.json"
+    },
+    "typesVersions": {
+        "*": {
+            "reasons": [
+                "./dist/reasons.d.ts"
+            ]
+        }
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint src --ext .ts"
+    },
+    "dependencies": {
+        "@coral-xyz/anchor": "^0.32.1",
+        "@solana/spl-token": "^0.4.14",
+        "@solana/web3.js": "^1.98.4",
+        "@types/bn.js": "^5.1.6",
+        "bn.js": "^5.2.1"
+    },
+    "devDependencies": {
+        "@solana/kit": "^5",
+        "@token-acl/sdk": "0.2.7",
+        "@types/node": "^20.0.0",
+        "@typescript-eslint/eslint-plugin": "^8.56.0",
+        "@typescript-eslint/parser": "^8.56.0",
+        "eslint": "^10.0.1",
+        "sas-lib": "1.0.10",
+        "tsup": "^8.0.0",
+        "typescript": "^5.4.0",
+        "vitest": "^4.0.18"
+    }
+}