@thawgate/sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2391 @@
+import { PublicKey, Connection, TransactionInstruction, Commitment, Signer, AccountMeta, Keypair, Transaction, VersionedTransaction } from '@solana/web3.js';
+import { AnchorProvider, Program } from '@coral-xyz/anchor';
+import BN from 'bn.js';
+export { default as BN } from 'bn.js';
+import { GateAction, GateVerdict } from './reasons.js';
+export { FLAG_CODES, FlagCode, GATE_DENY_ERRORS, GateLogs, STRUCTURAL_DENY_CODES, StructuralDenyCode, THAWGATE_GATE_ID, THAW_ALLOW_CODES, TgCode, ThawAllowCode, classifyGateLogs, describe as describeGateCode, isTgCode, parseGateLogs } from './reasons.js';
+
+/**
+ * Program IDL in camelCase format in order to be used in JS/TS.
+ *
+ * Note that this is only a type helper and is not the actual IDL. The original
+ * IDL can be found at `target/idl/thawgate_gate.json`.
+ */
+type ThawgateGate = {
+    "address": "THAW2daLXyUtCLtTsJWDTKZctiAGmGX4wT1kqKXugUZ";
+    "metadata": {
+        "name": "thawgateGate";
+        "version": "0.1.0";
+        "spec": "0.1.0";
+        "description": "ThawGate: Token ACL (sRFC 37) gating program with issuer blacklist, allowlist and SAS KYC policies";
+    };
+    "instructions": [
+        {
+            "name": "canFreezePermissionless";
+            "docs": [
+                "Token ACL gate interface: may this token account be frozen permissionlessly?"
+            ];
+            "discriminator": [
+                214,
+                141,
+                109,
+                75,
+                248,
+                1,
+                45,
+                29
+            ];
+            "accounts": [
+                {
+                    "name": "caller";
+                },
+                {
+                    "name": "tokenAccount";
+                },
+                {
+                    "name": "mint";
+                },
+                {
+                    "name": "owner";
+                },
+                {
+                    "name": "flagAccount";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "canThawPermissionless";
+            "docs": [
+                "Token ACL gate interface: may this token account be thawed permissionlessly?"
+            ];
+            "discriminator": [
+                8,
+                175,
+                169,
+                129,
+                137,
+                74,
+                61,
+                241
+            ];
+            "accounts": [
+                {
+                    "name": "caller";
+                },
+                {
+                    "name": "tokenAccount";
+                },
+                {
+                    "name": "mint";
+                },
+                {
+                    "name": "owner";
+                },
+                {
+                    "name": "flagAccount";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "initPolicy";
+            "docs": [
+                "Creates the mint's policy and its thaw/freeze extra-metas lists.",
+                "Signed by the Token ACL freeze authority; `args.authority` becomes the policy admin."
+            ];
+            "discriminator": [
+                45,
+                234,
+                110,
+                100,
+                209,
+                146,
+                191,
+                86
+            ];
+            "accounts": [
+                {
+                    "name": "freezeAuthority";
+                    "docs": [
+                        "Token ACL `MintConfig.freeze_authority` of this mint. Can be a PDA signing through CPI",
+                        "(the sss-token config in S6). The policy admin is `args.authority`, which may be someone else."
+                    ];
+                    "signer": true;
+                },
+                {
+                    "name": "payer";
+                    "docs": [
+                        "Pays rent. Separate from `freeze_authority`, since a program-owned PDA cannot fund `create_account`."
+                    ];
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "policy";
+                    "writable": true;
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const";
+                                "value": [
+                                    112,
+                                    111,
+                                    108,
+                                    105,
+                                    99,
+                                    121
+                                ];
+                            },
+                            {
+                                "kind": "account";
+                                "path": "mint";
+                            }
+                        ];
+                    };
+                },
+                {
+                    "name": "mint";
+                },
+                {
+                    "name": "mintConfig";
+                },
+                {
+                    "name": "thawExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "freezeExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                    "address": "11111111111111111111111111111111";
+                }
+            ];
+            "args": [
+                {
+                    "name": "args";
+                    "type": {
+                        "defined": {
+                            "name": "policyArgs";
+                        };
+                    };
+                }
+            ];
+        },
+        {
+            "name": "setupExtraMetas";
+            "docs": [
+                "Rewrites both extra-metas lists from the stored policy (idempotent)."
+            ];
+            "discriminator": [
+                160,
+                172,
+                133,
+                35,
+                114,
+                239,
+                51,
+                158
+            ];
+            "accounts": [
+                {
+                    "name": "authority";
+                    "signer": true;
+                    "relations": [
+                        "policy"
+                    ];
+                },
+                {
+                    "name": "payer";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "policy";
+                    "writable": true;
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const";
+                                "value": [
+                                    112,
+                                    111,
+                                    108,
+                                    105,
+                                    99,
+                                    121
+                                ];
+                            },
+                            {
+                                "kind": "account";
+                                "path": "mint";
+                            }
+                        ];
+                    };
+                },
+                {
+                    "name": "mint";
+                    "relations": [
+                        "policy"
+                    ];
+                },
+                {
+                    "name": "thawExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "freezeExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                    "address": "11111111111111111111111111111111";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "updatePolicy";
+            "docs": [
+                "Changes the policy and rewrites both extra-metas lists to match."
+            ];
+            "discriminator": [
+                212,
+                245,
+                246,
+                7,
+                163,
+                151,
+                18,
+                57
+            ];
+            "accounts": [
+                {
+                    "name": "authority";
+                    "signer": true;
+                    "relations": [
+                        "policy"
+                    ];
+                },
+                {
+                    "name": "payer";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "policy";
+                    "writable": true;
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const";
+                                "value": [
+                                    112,
+                                    111,
+                                    108,
+                                    105,
+                                    99,
+                                    121
+                                ];
+                            },
+                            {
+                                "kind": "account";
+                                "path": "mint";
+                            }
+                        ];
+                    };
+                },
+                {
+                    "name": "mint";
+                    "relations": [
+                        "policy"
+                    ];
+                },
+                {
+                    "name": "thawExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "freezeExtraMetas";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                    "address": "11111111111111111111111111111111";
+                }
+            ];
+            "args": [
+                {
+                    "name": "args";
+                    "type": {
+                        "defined": {
+                            "name": "policyArgs";
+                        };
+                    };
+                }
+            ];
+        }
+    ];
+    "accounts": [
+        {
+            "name": "gatePolicy";
+            "discriminator": [
+                3,
+                77,
+                45,
+                55,
+                30,
+                166,
+                143,
+                147
+            ];
+        }
+    ];
+    "errors": [
+        {
+            "code": 6000;
+            "name": "invalidMintConfig";
+            "msg": "Not a Token ACL MintConfig (owner, size or discriminator)";
+        },
+        {
+            "code": 6001;
+            "name": "mintConfigMismatch";
+            "msg": "The MintConfig belongs to a different mint";
+        },
+        {
+            "code": 6002;
+            "name": "notFreezeAuthority";
+            "msg": "Signer is not the Token ACL freeze authority of this mint";
+        },
+        {
+            "code": 6003;
+            "name": "notPolicyAuthority";
+            "msg": "Signer is not the policy authority";
+        },
+        {
+            "code": 6004;
+            "name": "invalidMint";
+            "msg": "Mint is not a Token-2022 mint";
+        },
+        {
+            "code": 6005;
+            "name": "invalidExtraMetasAccount";
+            "msg": "Extra-metas account is not the expected PDA";
+        },
+        {
+            "code": 6006;
+            "name": "missingIssuerProgram";
+            "msg": "issuer_program must be set when the blacklist or allowlist is enabled";
+        },
+        {
+            "code": 6007;
+            "name": "missingSasConfig";
+            "msg": "sas_credential and sas_schema must be set when require_sas is on";
+        },
+        {
+            "code": 6008;
+            "name": "bypassNeedsSas";
+            "msg": "BypassForPdas stands in for the SAS credential, so it needs require_sas";
+        },
+        {
+            "code": 6009;
+            "name": "deniedMissingAccounts";
+            "msg": "TG:DENY:MISSING_ACCOUNTS: extra accounts missing";
+        },
+        {
+            "code": 6010;
+            "name": "deniedBadPolicy";
+            "msg": "TG:DENY:BAD_POLICY: policy account is not this mint's GatePolicy";
+        },
+        {
+            "code": 6011;
+            "name": "deniedBadRegistryEntry";
+            "msg": "TG:DENY:BAD_REGISTRY_ENTRY: registry account has the wrong owner, type or fields";
+        },
+        {
+            "code": 6012;
+            "name": "deniedBadCredential";
+            "msg": "TG:DENY:BAD_CREDENTIAL: attestation account is not a SAS attestation of this credential, schema and owner";
+        },
+        {
+            "code": 6013;
+            "name": "deniedNoImmutableOwner";
+            "msg": "TG:DENY:NO_IMMUTABLE_OWNER: token account lacks the ImmutableOwner extension";
+        },
+        {
+            "code": 6014;
+            "name": "deniedBlacklisted";
+            "msg": "TG:DENY:BLACKLISTED: owner is on the issuer blacklist";
+        },
+        {
+            "code": 6015;
+            "name": "deniedNotAllowlisted";
+            "msg": "TG:DENY:NOT_ALLOWLISTED: owner is not on the issuer allowlist";
+        },
+        {
+            "code": 6016;
+            "name": "deniedNoCredential";
+            "msg": "TG:DENY:NO_CREDENTIAL: owner has no SAS attestation (never issued, or revoked)";
+        },
+        {
+            "code": 6017;
+            "name": "deniedCredentialExpired";
+            "msg": "TG:DENY:CREDENTIAL_EXPIRED: owner's SAS attestation has expired";
+        },
+        {
+            "code": 6018;
+            "name": "deniedKycLevelTooLow";
+            "msg": "TG:DENY:KYC_LEVEL_TOO_LOW: owner's kyc_level is below the policy minimum";
+        },
+        {
+            "code": 6019;
+            "name": "deniedCompliant";
+            "msg": "TG:DENY:COMPLIANT: owner passes the policy, so it cannot be frozen permissionlessly";
+        }
+    ];
+    "types": [
+        {
+            "name": "allowlistMode";
+            "docs": [
+                "How the issuer allowlist is used."
+            ];
+            "type": {
+                "kind": "enum";
+                "variants": [
+                    {
+                        "name": "off";
+                    },
+                    {
+                        "name": "allowOnly";
+                    },
+                    {
+                        "name": "bypassForPdas";
+                    }
+                ];
+            };
+        },
+        {
+            "name": "gatePolicy";
+            "docs": [
+                "One per mint. Token ACL resolves it for the gate as extra account `[6]`."
+            ];
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "version";
+                        "type": "u8";
+                    },
+                    {
+                        "name": "bump";
+                        "type": "u8";
+                    },
+                    {
+                        "name": "mint";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "authority";
+                        "docs": [
+                            "May change the policy (`update_policy`, `setup_extra_metas`)."
+                        ];
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "issuerProgram";
+                        "docs": [
+                            "Program that owns the registry (sss-token): `BlacklistEntry` at `[\"blacklist\", mint, wallet]`,",
+                            "`AllowlistEntry` at `[\"allowlist\", mint, wallet]`."
+                        ];
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "checkBlacklist";
+                        "type": "bool";
+                    },
+                    {
+                        "name": "allowlistMode";
+                        "type": {
+                            "defined": {
+                                "name": "allowlistMode";
+                            };
+                        };
+                    },
+                    {
+                        "name": "requireSas";
+                        "docs": [
+                            "SAS KYC policy: the owner needs a live attestation at `[\"attestation\", sas_credential, sas_schema, owner]`",
+                            "under SAS (nonce = holder wallet)."
+                        ];
+                        "type": "bool";
+                    },
+                    {
+                        "name": "sasCredential";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "sasSchema";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "minKycLevel";
+                        "docs": [
+                            "0 = any level. Otherwise compared with the attestation data's first byte, so the schema's first field must",
+                            "be `kyc_level: u8`."
+                        ];
+                        "type": "u8";
+                    },
+                    {
+                        "name": "reserved";
+                        "docs": [
+                            "Room for later policies (sanctions, keeper settings) without a realloc."
+                        ];
+                        "type": {
+                            "array": [
+                                "u8",
+                                64
+                            ];
+                        };
+                    }
+                ];
+            };
+        },
+        {
+            "name": "policyArgs";
+            "docs": [
+                "Settable policy fields, for `init_policy` and `update_policy`."
+            ];
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "authority";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "issuerProgram";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "checkBlacklist";
+                        "type": "bool";
+                    },
+                    {
+                        "name": "allowlistMode";
+                        "type": {
+                            "defined": {
+                                "name": "allowlistMode";
+                            };
+                        };
+                    },
+                    {
+                        "name": "requireSas";
+                        "type": "bool";
+                    },
+                    {
+                        "name": "sasCredential";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "sasSchema";
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "minKycLevel";
+                        "type": "u8";
+                    }
+                ];
+            };
+        }
+    ];
+};
+
+/**
+ * @module gate/tokenAcl
+ * @description Token ACL (sRFC 37) instructions on @solana/web3.js v1.
+ *
+ * Hand-built from @token-acl/sdk 0.2.7's generated code, which is @solana/kit-based (and its `*WithExtraMetas`
+ * builders print to the console). tests/tokenAcl.test.ts pins every builder here byte-for-byte against it. Extra
+ * account metas resolve with @solana/spl-token's resolver, the same algorithm @token-acl/sdk uses.
+ */
+
+/** Token ACL instruction discriminators (one byte). */
+declare const TOKEN_ACL_IX: {
+    readonly createConfig: 0;
+    readonly setAuthority: 1;
+    readonly setGatingProgram: 2;
+    readonly deleteConfig: 3;
+    readonly thaw: 4;
+    readonly freeze: 5;
+    readonly thawPermissionless: 6;
+    readonly freezePermissionless: 7;
+    readonly togglePermissionlessInstructions: 8;
+    readonly thawPermissionlessIdempotent: 9;
+    readonly freezePermissionlessIdempotent: 10;
+};
+/** `["MINT_CONFIG", mint]` under Token ACL. */
+declare function findMintConfigPda(mint: PublicKey, programId?: PublicKey): PublicKey;
+/** `["FLAG_ACCOUNT", tokenAccount]` under Token ACL: created and closed inside a permissionless thaw or freeze. */
+declare function findFlagAccountPda(tokenAccount: PublicKey, programId?: PublicKey): PublicKey;
+/** The gating program's extra-metas list for permissionless thaw: `["thaw_extra_account_metas", mint]` under the gate. */
+declare function findThawExtraMetasPda(mint: PublicKey, gatingProgram: PublicKey): PublicKey;
+/** The gating program's extra-metas list for permissionless freeze: `["freeze_extra_account_metas", mint]`. */
+declare function findFreezeExtraMetasPda(mint: PublicKey, gatingProgram: PublicKey): PublicKey;
+/** Token ACL's per-mint config. `freezeAuthority` may freeze, thaw and change the gate; it is the mint's freeze authority. */
+interface MintConfig {
+    bump: number;
+    enablePermissionlessThaw: boolean;
+    enablePermissionlessFreeze: boolean;
+    mint: PublicKey;
+    freezeAuthority: PublicKey;
+    gatingProgram: PublicKey;
+}
+/** u8 discriminator (1), bump, two flags, then three pubkeys. */
+declare const MINT_CONFIG_SIZE = 100;
+declare function decodeMintConfig(data: Buffer | Uint8Array): MintConfig;
+/** The mint's Token ACL config, or `null` if the mint has none (it is not a Token ACL mint). */
+declare function fetchMintConfig(connection: Connection, mint: PublicKey): Promise<MintConfig | null>;
+/** Switch the mint's gating program. Signed by the MintConfig freeze authority. */
+declare function setGatingProgramIx(args: {
+    authority: PublicKey;
+    mint: PublicKey;
+    gatingProgram: PublicKey;
+}): TransactionInstruction;
+/** Enable or disable permissionless freeze and thaw. Signed by the MintConfig freeze authority. */
+declare function togglePermissionlessIx(args: {
+    authority: PublicKey;
+    mint: PublicKey;
+    freeze: boolean;
+    thaw: boolean;
+}): TransactionInstruction;
+/**
+ * A permissionless Token ACL instruction. The idempotent variants return early, without calling the gate, when the
+ * account is already in the target state.
+ */
+type PermissionlessKind = "thaw" | "thawIdempotent" | "freeze" | "freezeIdempotent";
+interface PermissionlessArgs {
+    /** Signs and pays for the flag account's rent (refunded in the same instruction). Anyone may call. */
+    caller: PublicKey;
+    mint: PublicKey;
+    tokenAccount: PublicKey;
+    /** The token account's owner. Token ACL checks it against the account. */
+    owner: PublicKey;
+    /** The mint's config, if already fetched. */
+    mintConfig?: MintConfig;
+}
+/**
+ * Builds `thaw_permissionless` / `freeze_permissionless` (or an idempotent variant) with the gating program's extra
+ * accounts resolved, like @token-acl/sdk's `create*InstructionWithExtraMetas`.
+ *
+ * The gate receives `[caller, token_account, mint, owner, flag_account, extra_metas, ...extras]`. Its meta list's
+ * seeds index into that list, so the resolver starts from those six accounts and appends each resolved meta in turn
+ * (a later seed can reference an earlier extra, e.g. the attestation's credential and schema).
+ */
+declare function permissionlessIx(connection: Connection, kind: PermissionlessKind, args: PermissionlessArgs): Promise<TransactionInstruction>;
+
+/**
+ * @module gate/client
+ * @description GateClient: ThawGate policies and the holder-side flows (unlock, explain, freeze-if-invalid) for any
+ * Token ACL mint gated by ThawGate, whoever issued it. sss-token mints get it as `SolanaStablecoin#gate`.
+ *
+ * @example
+ * ```ts
+ * const gate = new GateClient(connection, wallet);
+ * const why = await gate.explain(mint, holder);          // simulate: may this wallet unlock? why not?
+ * await gate.send(await gate.createAtaAndThaw(mint, holder));
+ * await gate.freezeIfInvalid(tokenAccount);             // freezes only if the gate allows it
+ * ```
+ */
+
+/** An Anchor-style wallet: a public key that signs transactions. `keypairWallet(keypair)` makes one. */
+type GateWallet = AnchorProvider["wallet"];
+/** How the issuer's allowlist is used. `bypassForPdas` lets allowlisted program-owned accounts (pool vaults) skip SAS. */
+type AllowlistMode = "off" | "allowOnly" | "bypassForPdas";
+/** A policy, as you write it. Every field is optional; the defaults are off. */
+interface PolicyInput {
+    /** Deny holders with an active blacklist entry in the issuer program. */
+    checkBlacklist?: boolean;
+    allowlistMode?: AllowlistMode;
+    /** Require a live SAS attestation (nonce = the holder's wallet) under this credential and schema. `null` turns SAS off. */
+    sas?: {
+        credential: PublicKey;
+        schema: PublicKey;
+        minKycLevel?: number;
+    } | null;
+    /** Owner of the blacklist/allowlist entries. Default: sss-token when either list is on. Ignored by `enableTokenAcl`. */
+    issuerProgram?: PublicKey;
+    /** Who may change the policy. Default: the payer. Ignored by `enableTokenAcl` (it uses the issuer's authority). */
+    authority?: PublicKey;
+}
+/** A policy as stored on chain (`["policy", mint]` under the gate). */
+interface GatePolicy {
+    address: PublicKey;
+    version: number;
+    mint: PublicKey;
+    authority: PublicKey;
+    issuerProgram: PublicKey;
+    checkBlacklist: boolean;
+    allowlistMode: AllowlistMode;
+    requireSas: boolean;
+    sasCredential: PublicKey;
+    sasSchema: PublicKey;
+    minKycLevel: number;
+}
+/** What `explain` found. */
+interface Explanation {
+    mint: PublicKey;
+    wallet: PublicKey;
+    tokenAccount: PublicKey;
+    /** The token account before the simulation. */
+    account: "missing" | "frozen" | "thawed";
+    /**
+     * - `can_unlock`: the account is missing or frozen, and a permissionless thaw would succeed.
+     * - `denied`: a thaw would be refused (`code` says why).
+     * - `compliant`: the account is thawed and nobody can freeze it permissionlessly.
+     * - `freezable`: the account is thawed, but the policy flags the owner, so anyone can freeze it (`code` says why).
+     * - `not_token_acl`, `permissionless_disabled`, `error`: see `reason`.
+     */
+    status: "can_unlock" | "denied" | "compliant" | "freezable" | "not_token_acl" | "permissionless_disabled" | "error";
+    /** The gate's reason code (`KYC`, `NO_CREDENTIAL`, …), or null when the gate did not decide. */
+    code: string | null;
+    /** One sentence for a person. */
+    reason: string;
+    /** What was simulated: a thaw (missing or frozen account) or a freeze (thawed account). */
+    simulated: GateAction | null;
+    gatingProgram: PublicKey | null;
+    verdict: GateVerdict | null;
+    logs: string[];
+}
+interface FreezeResult {
+    frozen: boolean;
+    /** It was frozen before this call. */
+    alreadyFrozen: boolean;
+    code: string | null;
+    reason: string;
+    signature?: string;
+}
+/** sss-token's `GatePolicyConfig` (the `enable_token_acl` argument) from a PolicyInput. */
+declare function toGatePolicyConfig(p: PolicyInput): {
+    checkBlacklist: boolean;
+    allowlistMode: object;
+    requireSas: boolean;
+    sasCredential: PublicKey;
+    sasSchema: PublicKey;
+    minKycLevel: number;
+};
+interface GateClientOptions {
+    /** Default: the devnet ThawGate deployment. */
+    gateProgramId?: PublicKey;
+    commitment?: Commitment;
+}
+declare class GateClient {
+    readonly connection: Connection;
+    readonly wallet?: GateWallet | undefined;
+    readonly program: Program<ThawgateGate>;
+    readonly gateProgramId: PublicKey;
+    private readonly commitment;
+    /**
+     * @param connection - RPC connection.
+     * @param wallet - Signs and pays. Optional for read-only use (`explain`, `getPolicy`, builders with explicit payers).
+     */
+    constructor(connection: Connection, wallet?: GateWallet | undefined, opts?: GateClientOptions);
+    private me;
+    /** `["policy", mint]` under the gate. */
+    policyAddress(mint: PublicKey): PublicKey;
+    /** The mint's Token ACL config (freeze authority, gating program, permissionless flags), or null. */
+    getMintConfig(mint: PublicKey): Promise<MintConfig | null>;
+    /** The mint's ThawGate policy, or null if it has none. */
+    getPolicy(mint: PublicKey): Promise<GatePolicy | null>;
+    private metasAccounts;
+    /** Refuses mints whose Token ACL freeze authority is sss-token's config PDA: those get their policy from `enable_token_acl`. */
+    private freezeAuthorityOf;
+    /**
+     * Create the mint's policy and write both extra-metas lists. Signed by the Token ACL freeze authority of the mint
+     * (not for sss-token mints: `enableTokenAcl` does this there). The gating program is not switched; `swapGate` does both.
+     */
+    initPolicy(mint: PublicKey, policy: PolicyInput, opts?: {
+        freezeAuthority?: PublicKey;
+        payer?: PublicKey;
+    }): Promise<TransactionInstruction[]>;
+    /**
+     * Change the policy and rewrite both extra-metas lists. `changes` apply on top of the stored policy (`sas: null`
+     * turns SAS off). Signed by the policy authority: the issuer's wallet on sss-token mints.
+     */
+    updatePolicy(mint: PublicKey, changes: PolicyInput, opts?: {
+        authority?: PublicKey;
+        payer?: PublicKey;
+    }): Promise<TransactionInstruction[]>;
+    /** Rewrite both extra-metas lists from the stored policy (idempotent). Signed by the policy authority. */
+    setupExtraMetas(mint: PublicKey, opts?: {
+        authority?: PublicKey;
+        payer?: PublicKey;
+    }): Promise<TransactionInstruction[]>;
+    /**
+     * Move an existing Token ACL mint (e.g. on the ABL gate) to ThawGate in one transaction: create the policy (or
+     * rewrite it if it exists), `set_gating_program` to ThawGate, and enable permissionless thaw and freeze if either
+     * is off. Signed by the mint's Token ACL freeze authority.
+     *
+     * Token ACL clients that find the gate through the mint's `token_acl` metadata field (@token-acl/sdk's `*FromMint`
+     * builders) would keep resolving the old gate's accounts, so the field is updated too when it names another gate.
+     * That needs the metadata update authority (`metadataAuthority`, default the freeze authority); pass
+     * `skipMetadata: true` to leave it.
+     */
+    swapGate(mint: PublicKey, policy: PolicyInput, opts?: {
+        freezeAuthority?: PublicKey;
+        payer?: PublicKey;
+        metadataAuthority?: PublicKey;
+        skipMetadata?: boolean;
+    }): Promise<TransactionInstruction[]>;
+    /** Point the mint's `token_acl` metadata field at this gate, if the mint has the field and it names another program. */
+    private tokenAclMetadataIxs;
+    /** The owner's associated token account for a Token-2022 mint (off-curve owners allowed). */
+    ata(mint: PublicKey, owner: PublicKey): PublicKey;
+    /**
+     * Create the owner's ATA if missing, then thaw it permissionlessly through the gate (idempotent: a thawed account
+     * stays as is). Anyone can pay; the owner doesn't sign. If the gate would deny, the transaction fails: call
+     * `explain` first for the reason.
+     */
+    createAtaAndThaw(mint: PublicKey, owner: PublicKey, opts?: {
+        payer?: PublicKey;
+    }): Promise<TransactionInstruction[]>;
+    private readTokenAccount;
+    /**
+     * Why may (or can't) this wallet hold the token? Simulates the permissionless instruction that applies, with no
+     * signature and no state change:
+     * - the wallet's account is missing or frozen: create-ATA + thaw (would it unlock?);
+     * - it is thawed: freeze (could anyone freeze it?).
+     *
+     * The fee payer of the simulation must exist and, for a missing account, afford the ATA rent: `opts.payer`, else the
+     * client's wallet, else the policy authority.
+     */
+    explain(mint: PublicKey, wallet: PublicKey, opts?: {
+        payer?: PublicKey;
+        tokenAccount?: PublicKey;
+    }): Promise<Explanation>;
+    /**
+     * Freeze `tokenAccount` permissionlessly if, and only if, the gate allows it (the policy flags its owner). Simulates
+     * first and sends only on `TG:ALLOW`, so a compliant holder costs no fee. Needs a wallet: it signs and pays.
+     */
+    freezeIfInvalid(tokenAccount: PublicKey): Promise<FreezeResult>;
+    /** Simulate without signatures. `payerMissing` = the fee payer account doesn't exist. */
+    simulate(ixs: TransactionInstruction[], payer: PublicKey): Promise<{
+        err: unknown;
+        logs: string[];
+        errorCode?: number;
+        payerMissing: boolean;
+        unitsConsumed?: number;
+    }>;
+    /**
+     * Sign with the client's wallet, then with `signers`, send, and confirm. Returns the signature.
+     *
+     * The wallet signs first: Phantom asks for that order on multi-signer transactions (a wallet may change the
+     * transaction while signing, which would void signatures made before it). Anchor's `sendAndConfirm` signs the
+     * other way round, so it gets no signers here and a wallet that adds them after the real wallet has signed.
+     */
+    send(ixs: TransactionInstruction[], signers?: Signer[]): Promise<string>;
+}
+
+/**
+ * @module types
+ * @description TypeScript type definitions for the Solana Stablecoin Standard (SSS) SDK.
+ *
+ * These types mirror the on-chain Anchor program state and instruction arguments.
+ */
+
+/**
+ * Role types matching the on-chain RoleType enum.
+ * Numeric values match the Anchor discriminator bytes.
+ */
+declare enum RoleType {
+    MasterAuthority = 0,
+    Minter = 1,
+    Burner = 2,
+    Pauser = 3,
+    Blacklister = 4,
+    Seizer = 5
+}
+/**
+ * Minter quota period matching the on-chain QuotaPeriod enum.
+ */
+declare enum QuotaPeriod {
+    Daily = 0,
+    Weekly = 1,
+    Monthly = 2,
+    Lifetime = 3
+}
+/**
+ * Supported SSS preset tiers.
+ */
+declare enum SSSPreset {
+    /** Basic stablecoin — mint, burn, freeze, pause, roles */
+    SSS1 = "SSS-1",
+    /** Enhanced compliance — adds blacklist, seize, transfer hook */
+    SSS2 = "SSS-2",
+    /** Private stablecoin — confidential transfers + allowlist */
+    SSS3 = "SSS-3",
+    /** Token ACL mint gated by ThawGate (no transfer hook); the default for new mints */
+    SSS_ACL = "SSS-ACL",
+    /** Token ACL plus the SSS transfer hook */
+    SSS_BOTH = "SSS-Both"
+}
+/**
+ * How a mint enforces compliance (`StablecoinConfig.compliance_mode`, immutable).
+ */
+declare enum ComplianceMode {
+    /** Transfer hook on every transfer (legacy SSS-2). */
+    Hook = 0,
+    /** Token ACL: frozen-by-default accounts thawed through the ThawGate gate; no hook. */
+    Acl = 1,
+    /** Token ACL and the transfer hook. */
+    Both = 2
+}
+/**
+ * On-chain StablecoinConfig account data.
+ */
+interface StablecoinConfig {
+    /** The MasterAuthority who controls this stablecoin. */
+    authority: PublicKey;
+    /** The Token-2022 mint address. */
+    mint: PublicKey;
+    /** Human-readable name (max 32 chars). */
+    name: string;
+    /** Ticker symbol (max 10 chars). */
+    symbol: string;
+    /** Metadata URI (max 200 chars). */
+    uri: string;
+    /** Number of decimal places. */
+    decimals: number;
+    /** Whether permanent delegate extension is enabled (immutable). */
+    enablePermanentDelegate: boolean;
+    /** Whether transfer hook extension is enabled (immutable). */
+    enableTransferHook: boolean;
+    /** Whether new accounts are frozen by default (immutable). */
+    defaultAccountFrozen: boolean;
+    /** Whether token operations are currently paused. */
+    paused: boolean;
+    /** Total tokens minted (cumulative). */
+    totalMinted: BN;
+    /** Total tokens burned (cumulative). */
+    totalBurned: BN;
+    /** PDA bump seed. */
+    bump: number;
+    /** A `ComplianceMode` value (immutable; decodes as 0 = Hook on configs created before S6). */
+    complianceMode: number;
+}
+/**
+ * On-chain RoleRecord account data.
+ */
+interface RoleRecord {
+    /** The mint this role is associated with. */
+    mint: PublicKey;
+    /** The key that holds this role. */
+    holder: PublicKey;
+    /** The type of role. */
+    role: RoleType;
+    /** Whether the role is currently active. */
+    active: boolean;
+    /** Unix timestamp when the role was granted. */
+    grantedAt: BN;
+    /** PDA bump seed. */
+    bump: number;
+}
+/**
+ * On-chain MinterQuota account data.
+ */
+interface MinterQuota {
+    /** The mint this quota applies to. */
+    mint: PublicKey;
+    /** The minter this quota belongs to. */
+    minter: PublicKey;
+    /** Maximum amount that can be minted per period. */
+    limit: BN;
+    /** Amount already minted in current period. */
+    used: BN;
+    /** The quota period type. */
+    period: QuotaPeriod;
+    /** PDA bump seed. */
+    bump: number;
+}
+/**
+ * On-chain BlacklistEntry account data (SSS-2 only).
+ */
+interface BlacklistEntry {
+    /** The mint this entry applies to. */
+    mint: PublicKey;
+    /** The blacklisted wallet address. */
+    target: PublicKey;
+    /** Human-readable reason for blacklisting. */
+    reason: string;
+    /** Unix timestamp when added. */
+    addedAt: BN;
+    /** The operator who added the entry. */
+    addedBy: PublicKey;
+    /** Whether the entry is currently active. */
+    active: boolean;
+    /** PDA bump seed. */
+    bump: number;
+}
+/**
+ * On-chain PauseState account data.
+ */
+interface PauseState {
+    /** The mint this pause state applies to. */
+    mint: PublicKey;
+    /** Whether token operations are paused. */
+    paused: boolean;
+    /** Unix timestamp when last paused (0 if never). */
+    pausedAt: BN;
+    /** The operator who last paused. */
+    pausedBy: PublicKey;
+    /** PDA bump seed. */
+    bump: number;
+}
+/**
+ * Arguments for the initialize instruction.
+ */
+interface InitializeArgs {
+    /** Human-readable name (max 32 chars). */
+    name: string;
+    /** Ticker symbol (max 10 chars). */
+    symbol: string;
+    /** Metadata URI (max 200 chars). */
+    uri: string;
+    /** Number of decimal places. */
+    decimals: number;
+    /** Enable permanent delegate extension (SSS-2). */
+    enablePermanentDelegate: boolean;
+    /** Enable transfer hook extension (SSS-2). */
+    enableTransferHook: boolean;
+    /** Freeze new accounts by default. */
+    defaultAccountFrozen: boolean;
+    /** Transfer hook program ID (required if enableTransferHook=true). */
+    hookProgramId?: PublicKey;
+    /** Enable confidential transfers (SSS-3). */
+    enableConfidentialTransfers?: boolean;
+    /** Enable allowlist-based access control (SSS-3). */
+    enableAllowlist?: boolean;
+    /**
+     * How the mint enforces compliance (default `ComplianceMode.Hook`, the pre-S6 behavior). `Acl` and `Both` need
+     * `defaultAccountFrozen`; `Acl` takes no hook and `Both` requires it. Call `enable_token_acl` after initialize.
+     */
+    complianceMode?: ComplianceMode;
+}
+/**
+ * Arguments for updating a minter's quota.
+ */
+interface UpdateMinterArgs {
+    /** The minter's public key. */
+    minter: PublicKey;
+    /** Maximum mint amount per period. */
+    limit: BN;
+    /** The quota period. */
+    period: QuotaPeriod;
+}
+/**
+ * Arguments for granting/revoking a role.
+ */
+interface UpdateRolesArgs {
+    /** The key to grant/revoke the role for. */
+    holder: PublicKey;
+    /** The role type. */
+    role: RoleType;
+    /** Whether to activate or deactivate. */
+    active: boolean;
+}
+/**
+ * Arguments for adding a wallet to the blacklist.
+ */
+interface AddToBlacklistArgs {
+    /** The wallet to blacklist. */
+    target: PublicKey;
+    /** Human-readable reason (max 200 chars). */
+    reason: string;
+}
+/**
+ * Configuration for initializing the SDK client.
+ */
+interface SSSClientConfig {
+    /** Solana RPC endpoint URL. */
+    rpcUrl: string;
+    /** Commitment level for transactions. */
+    commitment?: "processed" | "confirmed" | "finalized";
+    /** Whether to skip preflight checks. */
+    skipPreflight?: boolean;
+    /** SSS-Token program ID (default: the devnet deployment, `SSS_TOKEN_PROGRAM_ID`). */
+    programId?: PublicKey;
+    /** Transfer Hook program ID (default: the devnet deployment, `TRANSFER_HOOK_PROGRAM_ID`). */
+    hookProgramId?: PublicKey;
+    /** ThawGate gate program ID (default: the devnet deployment, `THAWGATE_GATE_PROGRAM_ID`). */
+    gateProgramId?: PublicKey;
+}
+/**
+ * Result type for SDK operations that submit transactions.
+ */
+interface TransactionResult {
+    /** The transaction signature. */
+    signature: string;
+    /** The slot the transaction was confirmed in. */
+    slot?: number;
+    /** Any useful data returned from the transaction. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Options for transaction submission.
+ */
+interface TransactionOptions {
+    /** Whether to skip preflight simulation. */
+    skipPreflight?: boolean;
+    /** Maximum retries for transaction confirmation. */
+    maxRetries?: number;
+    /** Additional signers beyond the payer. */
+    additionalSigners?: unknown[];
+}
+/**
+ * Event emitted when a stablecoin is initialized.
+ */
+interface StablecoinInitializedEvent {
+    mint: PublicKey;
+    authority: PublicKey;
+    name: string;
+    symbol: string;
+    decimals: number;
+    enablePermanentDelegate: boolean;
+    enableTransferHook: boolean;
+    defaultAccountFrozen: boolean;
+    timestamp: BN;
+}
+/**
+ * Event emitted when authority is transferred.
+ */
+interface AuthorityTransferredEvent {
+    mint: PublicKey;
+    oldAuthority: PublicKey;
+    newAuthority: PublicKey;
+    timestamp: BN;
+}
+/**
+ * Event emitted when tokens are seized.
+ */
+interface TokensSeizedEvent {
+    mint: PublicKey;
+    source: PublicKey;
+    treasury: PublicKey;
+    amount: BN;
+    seizer: PublicKey;
+    timestamp: BN;
+}
+
+/**
+ * @module modules/compliance
+ * @description ComplianceModule class for SSS-2 compliance operations.
+ *
+ * Provides blacklist management and token seizure capabilities.
+ * All methods are feature-gated — they throw FeatureNotEnabledError
+ * if the stablecoin was not initialized with SSS-2 features.
+ */
+
+/**
+ * ComplianceModule — SSS-2 compliance operations.
+ *
+ * Encapsulates blacklist and seizure operations. Validates that the
+ * stablecoin has SSS-2 features enabled before executing.
+ *
+ * @example
+ * ```ts
+ * const compliance = new ComplianceModule(program, mint, config);
+ *
+ * // Add to blacklist
+ * const ixs = await compliance.addToBlacklist(operator, target, "OFAC sanctioned");
+ *
+ * // Seize tokens
+ * const seizeIxs = await compliance.seize(seizer, sourceTokenAccount, treasury);
+ * ```
+ */
+declare class ComplianceModule {
+    private readonly program;
+    private readonly mint;
+    private readonly programId;
+    constructor(program: Program, mint: PublicKey);
+    /**
+     * Adds an address to the blacklist and freezes their token account.
+     *
+     * @param operator - The Blacklister operator's public key
+     * @param target - The wallet to blacklist
+     * @param reason - Human-readable reason (max 200 chars)
+     * @param opts.targetTokenAccount - The target's token account to pass (default: its ATA). sss-token requires an
+     *   account owned by `target` (S9); on Token ACL mints it is frozen in the same transaction if thawed.
+     * @returns Transaction instructions
+     * @throws FeatureNotEnabledError if transfer_hook is not enabled
+     */
+    addToBlacklist(operator: PublicKey, target: PublicKey, reason: string, opts?: {
+        targetTokenAccount?: PublicKey;
+    }): Promise<TransactionInstruction[]>;
+    /**
+     * Removes an address from the blacklist.
+     *
+     * Does NOT automatically thaw the account — call thawAccount separately.
+     *
+     * @param operator - The Blacklister operator's public key
+     * @param target - The wallet to remove from blacklist
+     * @returns Transaction instructions
+     */
+    removeFromBlacklist(operator: PublicKey, target: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Adds a wallet to the issuer allowlist (`add_to_allowlist_v3`, MasterAuthority). Needs a mint initialized with
+     * `enableAllowlist`; a ThawGate `allowOnly` or `bypassForPdas` policy reads the entry.
+     */
+    addToAllowlist(authority: PublicKey, wallet: PublicKey): Promise<TransactionInstruction[]>;
+    /** Deactivates a wallet's allowlist entry (`remove_from_allowlist_v3`, MasterAuthority). */
+    removeFromAllowlist(authority: PublicKey, wallet: PublicKey): Promise<TransactionInstruction[]>;
+    private allowlistIx;
+    /**
+     * Seizes all tokens from a frozen, blacklisted account.
+     *
+     * Requires both enable_transfer_hook and enable_permanent_delegate.
+     *
+     * @param seizer - The Seizer operator's public key
+     * @param sourceAuthority - The owner of the source token account
+     * @param sourceTokenAccount - The frozen token account to seize from
+     * @param treasuryTokenAccount - The treasury to receive seized tokens
+     * @returns Transaction instructions
+     */
+    seize(seizer: PublicKey, sourceAuthority: PublicKey, sourceTokenAccount: PublicKey, treasuryTokenAccount: PublicKey, remainingAccounts?: AccountMeta[]): Promise<TransactionInstruction[]>;
+    /**
+     * Fetches a blacklist entry for a given target.
+     *
+     * @param target - The wallet to check
+     * @returns The BlacklistEntry or null if not found
+     */
+    getBlacklistEntry(target: PublicKey): Promise<BlacklistEntry | null>;
+    /**
+     * Checks if a wallet is currently blacklisted.
+     *
+     * @param target - The wallet to check
+     * @returns true if actively blacklisted
+     */
+    isBlacklisted(target: PublicKey): Promise<boolean>;
+}
+
+/**
+ * @module modules/privacy
+ * @description Privacy module placeholder for SSS-3 (confidential transfers).
+ *
+ * SSS-3 will leverage SPL Confidential Transfer extension
+ * for zero-knowledge proof-based privacy-preserving transfers.
+ *
+ * This module is a placeholder for future implementation.
+ */
+
+/**
+ * PrivacyModule — SSS-3 confidential transfer operations (placeholder).
+ *
+ * @remarks
+ * This module will be implemented when SPL Confidential Transfer
+ * extension support is mature and audited.
+ */
+declare class PrivacyModule {
+    private readonly mint;
+    constructor(mint: PublicKey);
+    /**
+     * Initializes confidential transfer extension for the mint.
+     * @throws FeatureNotEnabledError — SSS-3 is not yet implemented
+     */
+    initializeConfidentialTransfer(): Promise<never>;
+    /**
+     * Creates a confidential transfer.
+     * @throws FeatureNotEnabledError — SSS-3 is not yet implemented
+     */
+    confidentialTransfer(): Promise<never>;
+    /**
+     * Retrieves the confidential balance of a token account.
+     * @throws FeatureNotEnabledError — SSS-3 is not yet implemented
+     */
+    getConfidentialBalance(): Promise<never>;
+}
+
+/**
+ * @module modules/reserves
+ * @description ReservesModule: the reserve attestation that `mint_tokens` checks (S9).
+ *
+ * MasterAuthority sets the attestor and the staleness window; the attestor posts reserves. `mint_tokens` then
+ * refuses a mint when `mint.supply + amount > reserves` (ReserveInsufficient) or `now - asOf > maxStaleness`
+ * (ReserveStale). Reserves are in the mint's base units (1.00 of a 6-decimal coin = 1_000_000).
+ * Acl/Both mode mints need an attestation to mint at all; Hook mode mints are checked once one exists.
+ */
+
+/** On-chain `ReserveAttestation` (PDA `["reserve_attestation", mint]`). */
+interface ReserveAttestation {
+    mint: PublicKey;
+    attestor: PublicKey;
+    /** Base units of the mint. */
+    reserves: BN;
+    /** Unix seconds at which the reserves were measured; 0 until the first post. */
+    asOf: BN;
+    /** Seconds after `asOf` during which minting may rely on the attestation. */
+    maxStaleness: BN;
+    reportUri: string;
+    /** Cluster time of the last post; 0 until the first post. */
+    postedAt: BN;
+    bump: number;
+}
+/**
+ * @example
+ * ```ts
+ * const reserves = client.reserves(mint);
+ * await reserves.setReserveAttestor(master, attestor, 86_400);          // MasterAuthority
+ * await reserves.attestReserves(attestor, new BN(1_000_000_000), asOf, "https://example.com/report.json");
+ * ```
+ */
+declare class ReservesModule {
+    private readonly program;
+    private readonly mint;
+    private readonly programId;
+    constructor(program: Program, mint: PublicKey);
+    /** The mint's ReserveAttestation address. */
+    address(): PublicKey;
+    /**
+     * Sets the attestor and the staleness window (seconds). MasterAuthority only; creates the account on first
+     * use. A different attestor clears the posted reserves, so minting waits for its first post.
+     */
+    setReserveAttestor(authority: PublicKey, attestor: PublicKey, maxStalenessSeconds: number | BN): Promise<TransactionInstruction[]>;
+    /**
+     * Posts reserves (base units) measured at `asOf` (unix seconds). Signed by the attestor. `asOf` may not be in
+     * the future or older than the stored one; `reportUri` is at most 200 bytes.
+     */
+    attestReserves(attestor: PublicKey, reserves: BN, asOf: number | BN, reportUri: string): Promise<TransactionInstruction[]>;
+    /** The mint's attestation, or null if MasterAuthority never set an attestor. */
+    fetch(): Promise<ReserveAttestation | null>;
+}
+
+/**
+ * @module client
+ * @description SolanaStablecoin — the main SDK entrypoint class.
+ *
+ * Provides a high-level, ergonomic API for interacting with SSS stablecoins.
+ * Wraps all base operations, role management, and compliance modules.
+ *
+ * @example
+ * ```ts
+ * import { SolanaStablecoin, sss1Preset } from "@thawgate/sdk";
+ *
+ * const client = SolanaStablecoin.fromConfig({
+ *   rpcUrl: "https://api.devnet.solana.com",
+ *   programId: new PublicKey("..."),
+ * });
+ *
+ * // Initialize a new SSS-1 stablecoin
+ * const { instructions, mint } = await client.initialize(
+ *   authority.publicKey,
+ *   sss1Preset("USD Stablecoin", "USDS", "https://meta.example.com", 6),
+ * );
+ * ```
+ */
+
+type Amount = BN | bigint | number | string;
+/** Options for {@link SolanaStablecoin.createStablecoin}. Amounts are base units (10^decimals per token). */
+interface CreateStablecoinOptions {
+    name: string;
+    symbol: string;
+    uri?: string;
+    /** Default 6. */
+    decimals?: number;
+    /** The ThawGate policy. `issuerProgram` and `authority` are set by sss-token (itself, and the issuer's wallet). */
+    policy: PolicyInput;
+    reserves: {
+        /** Reserves to post now, in base units: the supply can't exceed it. */
+        amount: Amount;
+        /** Link to the reserve report (at most 200 bytes). */
+        reportUri: string;
+        /** How old a post may be before minting stops. Default 86,400 s (1 day). */
+        maxStalenessSeconds?: number;
+        /** Who posts reserves. Default: the wallet, which then posts `amount` now; another attestor posts later. */
+        attestor?: PublicKey;
+    };
+    /** The Minter role and quota; default the wallet with quota = reserves, lifetime. `false` grants none. */
+    minter?: {
+        address?: PublicKey;
+        quota?: Amount;
+        period?: QuotaPeriod;
+    } | false;
+    /** Create the mint with the sss-token allowlist on. Default: on when the policy's allowlistMode isn't "off". */
+    enableAllowlist?: boolean;
+    /** The mint's keypair (vanity addresses); generated by default. */
+    mintKeypair?: Keypair;
+}
+interface CreatedStablecoin {
+    mint: PublicKey;
+    signatures: {
+        initialize: string;
+        enableTokenAcl: string;
+        setup: string;
+    };
+}
+/** Options for {@link SolanaStablecoin.initializeStablecoin}: the mint part of {@link CreateStablecoinOptions}. */
+type InitializeStablecoinOptions = Pick<CreateStablecoinOptions, "name" | "symbol" | "uri" | "decimals" | "enableAllowlist" | "mintKeypair">;
+/** Options for {@link SolanaStablecoin.setupMinting}: the reserves and minter part of {@link CreateStablecoinOptions}. */
+type SetupMintingOptions = Pick<CreateStablecoinOptions, "reserves" | "minter">;
+/**
+ * SolanaStablecoin — main SDK class.
+ *
+ * Acts as a facade over all SSS operations. Provides both
+ * instruction builders (for composability) and convenience
+ * methods for common workflows.
+ */
+declare class SolanaStablecoin {
+    /** The Anchor program instance. */
+    readonly program: Program;
+    /** The Solana connection. */
+    readonly connection: Connection;
+    /** The SSS-Token program ID. */
+    readonly programId: PublicKey;
+    /** The transfer hook program ID. */
+    readonly hookProgramId: PublicKey;
+    /** The signing wallet, if the client was created with one. */
+    readonly wallet?: AnchorProvider["wallet"];
+    /** ThawGate policies and holder flows (unlock, explain, freeze-if-invalid) for this client's mints. */
+    readonly gate: GateClient;
+    private constructor();
+    /**
+     * Creates a new SolanaStablecoin instance.
+     *
+     * Primary static factory method as required by the SSS PRD specification.
+     * Accepts a Connection object directly (PRD pattern) or creates one from config.rpcUrl.
+     *
+     * @param connectionOrConfig - A Solana Connection, or SSSClientConfig
+     * @param configOrWallet - SSSClientConfig if first arg is Connection, or wallet
+     * @param wallet - Anchor wallet (optional for read-only)
+     * @returns A new SolanaStablecoin instance
+     */
+    static create(connectionOrConfig: Connection | SSSClientConfig, configOrWallet?: SSSClientConfig | AnchorProvider["wallet"], wallet?: AnchorProvider["wallet"]): Promise<SolanaStablecoin>;
+    /**
+     * Creates a new SolanaStablecoin instance from configuration.
+     *
+     * Alias for {@link SolanaStablecoin.create} — kept for backward compatibility.
+     *
+     * @param config - Client configuration
+     * @param walletOrKeypair - Anchor wallet or a Keypair (optional for read-only)
+     * @returns A new SolanaStablecoin instance
+     */
+    static fromConfig(config: SSSClientConfig, walletOrKeypair?: AnchorProvider["wallet"] | Keypair): SolanaStablecoin;
+    private requireWallet;
+    /**
+     * sss-token `enable_token_acl`: creates the mint's Token ACL config (gate = ThawGate, permissionless thaw and
+     * freeze on) and its ThawGate policy, with the issuer's master authority as policy authority and sss-token as
+     * the blacklist/allowlist program. MasterAuthority only.
+     */
+    enableTokenAcl(mint: PublicKey, policy: PolicyInput, authority?: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Creates an SSS-ACL stablecoin gated by ThawGate, ready to mint, in three transactions:
+     * 1. `initialize` with the SSS-ACL preset (accounts start frozen);
+     * 2. `enable_token_acl` with `policy`;
+     * 3. the minter role and quota, the reserve attestor, and (when the wallet is the attestor) a first reserve post.
+     *
+     * The wallet becomes MasterAuthority and the policy authority. Minting needs reserves: every `mint_tokens`
+     * checks `supply + amount <= reserves` and that the post is fresher than `maxStalenessSeconds`.
+     */
+    createStablecoin(opts: CreateStablecoinOptions): Promise<CreatedStablecoin>;
+    /** createStablecoin's 1st transaction: `initialize` with the SSS-ACL preset (accounts start frozen). Allowlist off by default. */
+    initializeStablecoin(opts: InitializeStablecoinOptions): Promise<{
+        mint: PublicKey;
+        signature: string;
+    }>;
+    /** createStablecoin's 2nd transaction: `enable_token_acl` with `policy`, sent with the compute budget it needs. */
+    sendEnableTokenAcl(mint: PublicKey, policy: PolicyInput): Promise<string>;
+    /**
+     * createStablecoin's 3rd transaction: the minter role and quota, the reserve attestor, and (when the wallet is the
+     * attestor) a first reserve post.
+     */
+    setupMinting(mint: PublicKey, opts: SetupMintingOptions): Promise<string>;
+    /**
+     * The cluster's unix time (Clock sysvar). Reserve posts must use it: `attest_reserves` refuses an `as_of` in the
+     * future, and a local clock can run ahead of the cluster.
+     */
+    clusterTime(): Promise<number>;
+    /** Sign with the client's wallet (plus `signers`), send, and confirm. Returns the signature. */
+    send(instructions: TransactionInstruction[], signers?: Signer[]): Promise<string>;
+    /**
+     * Initializes a new stablecoin.
+     *
+     * @param authority - The authority's public key (becomes MasterAuthority)
+     * @param args - Initialization arguments (use sss1Preset or sss2Preset)
+     * @param mintKeypair - Optional mint keypair (generated if not provided)
+     */
+    initialize(authority: PublicKey, args: InitializeArgs, mintKeypair?: Keypair): Promise<{
+        instructions: TransactionInstruction[];
+        mint: PublicKey;
+        mintKeypair: Keypair;
+    }>;
+    /**
+     * Mints tokens to a recipient.
+     */
+    mintTokens(mint: PublicKey, minter: PublicKey, recipient: PublicKey, amount: BN): Promise<TransactionInstruction[]>;
+    /**
+     * Burns tokens from the burner's account.
+     */
+    burnTokens(mint: PublicKey, burner: PublicKey, amount: BN): Promise<TransactionInstruction[]>;
+    /**
+     * Freezes a target token account.
+     */
+    freezeAccount(mint: PublicKey, operator: PublicKey, targetTokenAccount: PublicKey, operatorRole?: RoleType.MasterAuthority | RoleType.Blacklister): Promise<TransactionInstruction[]>;
+    /**
+     * Thaws a frozen token account.
+     */
+    thawAccount(mint: PublicKey, operator: PublicKey, targetTokenAccount: PublicKey, operatorRole?: RoleType.MasterAuthority | RoleType.Blacklister): Promise<TransactionInstruction[]>;
+    /**
+     * Pauses all token operations.
+     */
+    pause(mint: PublicKey, operator: PublicKey, operatorRole?: RoleType.Pauser | RoleType.MasterAuthority): Promise<TransactionInstruction[]>;
+    /**
+     * Resumes all token operations.
+     */
+    unpause(mint: PublicKey, operator: PublicKey, operatorRole?: RoleType.Pauser | RoleType.MasterAuthority): Promise<TransactionInstruction[]>;
+    /**
+     * Creates or updates a minter with a quota.
+     */
+    updateMinter(mint: PublicKey, authority: PublicKey, minter: PublicKey, limit: BN, period: QuotaPeriod): Promise<TransactionInstruction[]>;
+    /**
+     * Creates or updates a role for a given key.
+     */
+    updateRoles(mint: PublicKey, authority: PublicKey, holder: PublicKey, role: RoleType, active: boolean): Promise<TransactionInstruction[]>;
+    /**
+     * Transfers MasterAuthority to a new key.
+     */
+    transferAuthority(mint: PublicKey, authority: PublicKey, newAuthority: PublicKey): Promise<TransactionInstruction[]>;
+    /**
+     * Returns a ComplianceModule for SSS-2 operations on a specific mint.
+     */
+    compliance(mint: PublicKey): ComplianceModule;
+    /**
+     * Returns a PrivacyModule for SSS-3 operations on a specific mint.
+     */
+    privacy(mint: PublicKey): PrivacyModule;
+    /**
+     * Returns a ReservesModule for the reserve attestation that `mint_tokens` checks.
+     */
+    reserves(mint: PublicKey): ReservesModule;
+    /**
+     * Typed account fetch helper.
+     * Wraps Anchor's program.account access with proper typing.
+     */
+    private fetchAccount;
+    /**
+     * Fetches the StablecoinConfig for a mint.
+     */
+    getConfig(mint: PublicKey): Promise<StablecoinConfig>;
+    /**
+     * Fetches the PauseState for a mint.
+     */
+    getPauseState(mint: PublicKey): Promise<PauseState>;
+    /**
+     * Fetches a role record for a given holder and role.
+     */
+    getRoleRecord(mint: PublicKey, holder: PublicKey, role: RoleType): Promise<RoleRecord | null>;
+    /**
+     * Fetches a minter's quota.
+     */
+    getMinterQuota(mint: PublicKey, minter: PublicKey): Promise<MinterQuota | null>;
+    /**
+     * Checks if a wallet has a specific active role.
+     */
+    hasRole(mint: PublicKey, holder: PublicKey, role: RoleType): Promise<boolean>;
+    /**
+     * Checks if the token is currently paused.
+     */
+    isPaused(mint: PublicKey): Promise<boolean>;
+}
+
+/**
+ * @module wallet
+ * @description An Anchor-style wallet from a Keypair, for scripts and servers (browser apps pass their wallet adapter).
+ */
+
+interface KeypairWallet {
+    publicKey: Keypair["publicKey"];
+    payer: Keypair;
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+declare function keypairWallet(keypair: Keypair): KeypairWallet;
+
+/**
+ * @module sas
+ * @description Solana Attestation Service (SAS) instructions on @solana/web3.js v1: credentials, schemas and
+ * attestations, enough to issue the KYC credential a ThawGate policy checks.
+ *
+ * Hand-built from sas-lib 1.0.10's generated code (sas-lib is @solana/kit-based); tests/sas.test.ts pins each builder
+ * byte-for-byte against it.
+ *
+ * A credential you create yourself is a **self-issued test credential**: it proves the flow, not anyone's identity.
+ * In production the policy names a KYC provider's credential and schema, and the provider issues attestations.
+ */
+
+declare const SAS_IX: {
+    readonly createCredential: 0;
+    readonly createSchema: 1;
+    readonly createAttestation: 6;
+    readonly closeAttestation: 7;
+};
+/** `["credential", authority, name]`. */
+declare function findCredentialPda(authority: PublicKey, name: string): PublicKey;
+/** `["schema", credential, name, version]`. A new schema is version 1. */
+declare function findSchemaPda(credential: PublicKey, name: string, version?: number): PublicKey;
+/** `["attestation", credential, schema, nonce]`. ThawGate policies use `nonce = the holder's wallet`. */
+declare function findAttestationPda(credential: PublicKey, schema: PublicKey, nonce: PublicKey): PublicKey;
+/** SAS's event authority, `["__event_authority"]`: `close_attestation` emits its event through it. */
+declare const SAS_EVENT_AUTHORITY: PublicKey;
+/** A credential: `authority` and the `signers` may issue attestations under it. Returns the instruction and its PDA. */
+declare function createCredentialIx(args: {
+    payer: PublicKey;
+    authority: PublicKey;
+    name: string;
+    signers?: PublicKey[];
+}): {
+    instruction: TransactionInstruction;
+    credential: PublicKey;
+};
+/** A schema under a credential. `layout` holds SAS compact type codes (0 = u8, 12 = String, …), one per field. */
+declare function createSchemaIx(args: {
+    payer: PublicKey;
+    authority: PublicKey;
+    credential: PublicKey;
+    name: string;
+    description: string;
+    layout: number[];
+    fieldNames: string[];
+}): {
+    instruction: TransactionInstruction;
+    schema: PublicKey;
+};
+/**
+ * An attestation of `data` (encoded to the schema's layout) for `nonce`. `expiry` is a unix timestamp; 0 = never.
+ * `authority` must be one of the credential's signers.
+ */
+declare function createAttestationIx(args: {
+    payer: PublicKey;
+    authority: PublicKey;
+    credential: PublicKey;
+    schema: PublicKey;
+    nonce: PublicKey;
+    data: Uint8Array;
+    expiry: number | bigint;
+}): {
+    instruction: TransactionInstruction;
+    attestation: PublicKey;
+};
+/** Close (revoke) an attestation; the rent goes to `payer`. Under a ThawGate SAS policy the holder becomes freezable. */
+declare function closeAttestationIx(args: {
+    payer: PublicKey;
+    authority: PublicKey;
+    credential: PublicKey;
+    attestation: PublicKey;
+}): TransactionInstruction;
+/**
+ * The KYC schema layout ThawGate reads: `kyc_level: u8` must come first (the gate reads it at a fixed offset when the
+ * policy sets `min_kyc_level`), then `country: String`.
+ */
+declare const KYC_SCHEMA: {
+    readonly layout: readonly [0, 12];
+    readonly fieldNames: readonly ["kyc_level", "country"];
+};
+/** Attestation data for {@link KYC_SCHEMA}: u8 kyc_level, then u32-length-prefixed UTF-8 country. */
+declare function encodeKycData(args: {
+    kycLevel: number;
+    country: string;
+}): Uint8Array;
+
+declare const index_KYC_SCHEMA: typeof KYC_SCHEMA;
+declare const index_SAS_EVENT_AUTHORITY: typeof SAS_EVENT_AUTHORITY;
+declare const index_SAS_IX: typeof SAS_IX;
+declare const index_closeAttestationIx: typeof closeAttestationIx;
+declare const index_createAttestationIx: typeof createAttestationIx;
+declare const index_createCredentialIx: typeof createCredentialIx;
+declare const index_createSchemaIx: typeof createSchemaIx;
+declare const index_encodeKycData: typeof encodeKycData;
+declare const index_findAttestationPda: typeof findAttestationPda;
+declare const index_findCredentialPda: typeof findCredentialPda;
+declare const index_findSchemaPda: typeof findSchemaPda;
+declare namespace index {
+  export { index_KYC_SCHEMA as KYC_SCHEMA, index_SAS_EVENT_AUTHORITY as SAS_EVENT_AUTHORITY, index_SAS_IX as SAS_IX, index_closeAttestationIx as closeAttestationIx, index_createAttestationIx as createAttestationIx, index_createCredentialIx as createCredentialIx, index_createSchemaIx as createSchemaIx, index_encodeKycData as encodeKycData, index_findAttestationPda as findAttestationPda, index_findCredentialPda as findCredentialPda, index_findSchemaPda as findSchemaPda };
+}
+
+/**
+ * @module programs
+ * @description Program IDs the SDK talks to. ThawGate's own programs are deployed on devnet (localnet uses the same
+ * IDs); Token ACL, SAS and the ABL gate are the upstream deployments, the same address on devnet and mainnet.
+ */
+
+/** sss-token, the example issuer (devnet). */
+declare const SSS_TOKEN_PROGRAM_ID: PublicKey;
+/** The SSS transfer hook (devnet). Used by SSS-2 and Both mints only. */
+declare const TRANSFER_HOOK_PROGRAM_ID: PublicKey;
+/** The ThawGate gating program (devnet; unaudited, never deployed to mainnet). */
+declare const THAWGATE_GATE_PROGRAM_ID: PublicKey;
+/** Token ACL (sRFC 37). */
+declare const TOKEN_ACL_PROGRAM_ID: PublicKey;
+/** Solana Attestation Service. */
+declare const SAS_PROGRAM_ID: PublicKey;
+/** Token ACL's reference allow/block-list gate (ABL). */
+declare const ABL_GATE_PROGRAM_ID: PublicKey;
+
+/**
+ * @module errors
+ * @description Error class hierarchy for the SSS SDK.
+ *
+ * Maps on-chain Anchor error codes to typed JavaScript errors. The code → name → message tables come from the
+ * programs' IDLs (`src/idl.json`, `src/gate/idl.json`), which CI compares byte for byte with its own `anchor build`.
+ */
+/**
+ * Base error class for all SSS SDK errors.
+ */
+declare class SSSError extends Error {
+    /** The Anchor error code (if from on-chain). */
+    readonly code?: number;
+    /** The original error that caused this one. */
+    readonly cause?: Error;
+    /** The program's name for the error, from its IDL (e.g. `"ReserveInsufficient"`), when a program raised it. */
+    readonly errorName?: string;
+    /** The program that raised it (base58), when known. */
+    readonly program?: string;
+    constructor(message: string, code?: number, cause?: Error);
+    /**
+     * Alias for `code` — spec requires the field to be named `errorCode`.
+     * LOW-002: added getter for spec API surface compatibility.
+     */
+    get errorCode(): number | undefined;
+}
+/**
+ * Error thrown when a transaction fails on-chain.
+ */
+declare class TransactionError extends SSSError {
+    /** The transaction signature (if available). */
+    readonly signature?: string;
+    /** The transaction logs (if available). */
+    readonly logs?: string[];
+    constructor(message: string, code?: number, signature?: string, logs?: string[]);
+}
+/**
+ * Error thrown when authorization/permission checks fail.
+ */
+declare class AuthorizationError extends SSSError {
+    constructor(message: string, code?: number);
+}
+/**
+ * Error thrown when the token is paused and the operation is blocked.
+ */
+declare class TokenPausedError extends SSSError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a feature is not enabled (e.g., SSS-2 operations on SSS-1).
+ */
+declare class FeatureNotEnabledError extends SSSError {
+    constructor(feature: string);
+}
+/**
+ * Error thrown when an account is blacklisted.
+ */
+declare class BlacklistedError extends SSSError {
+    constructor(address: string);
+}
+/**
+ * Error thrown when a minter exceeds their quota.
+ */
+declare class QuotaExceededError extends SSSError {
+    /** The current quota limit. */
+    readonly limit: bigint;
+    /** The amount already used. */
+    readonly used: bigint;
+    /** The amount that was attempted. */
+    readonly attempted: bigint;
+    /** `message` replaces the default text, e.g. when the amounts aren't known (a program error). */
+    constructor(limit: bigint, used: bigint, attempted: bigint, message?: string);
+}
+/**
+ * Error thrown for invalid configuration or arguments.
+ */
+declare class ConfigError extends SSSError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when an account is not found on-chain.
+ */
+declare class AccountNotFoundError extends SSSError {
+    constructor(accountType: string, address: string);
+}
+/** One error a program declares in its IDL. */
+interface ProgramErrorInfo {
+    /** The declaring program (base58, the IDL's `address`). */
+    program: string;
+    code: number;
+    name: string;
+    msg: string;
+}
+/** sss-token's errors by code, from its IDL. */
+declare const SSS_TOKEN_ERRORS: Readonly<Record<number, ProgramErrorInfo>>;
+/** The ThawGate gate's errors by code, from its IDL. */
+declare const THAWGATE_GATE_ERRORS: Readonly<Record<number, ProgramErrorInfo>>;
+/** The IDL entry for `code` raised by `program` (base58); undefined for a program or code the SDK doesn't know. */
+declare function programError(program: string, code: number): ProgramErrorInfo | undefined;
+/**
+ * Parses an error from a program call into a typed SSSError.
+ *
+ * Reads, in order: an Anchor `AnchorError` (`error.errorCode.number` and `program`); a numeric `code` (Anchor's
+ * `ProgramError`, raised by the SDK's sss-token calls); the transaction logs (`logs`, as on web3.js's
+ * `SendTransactionError` from `client.send`). Codes are looked up in the raising program's IDL; a program the SDK
+ * doesn't know (Token-2022, Token ACL, …) is left unmapped. A code without a program is read as sss-token's.
+ *
+ * @param error - The raw error from Anchor/web3.js
+ * @returns A typed SSSError instance
+ */
+declare function parseError(error: unknown): SSSError;
+/**
+ * @spec SssError — base error class alias required by the SSS spec.
+ */
+declare class SssError extends SSSError {
+    constructor(message: string, code?: number, cause?: Error);
+}
+/**
+ * @spec SssInitError — initialization error class required by the SSS spec.
+ * Maps to TransactionError for initialization transactions.
+ */
+declare class SssInitError extends SSSError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * @spec SssMintError — minting error class required by the SSS spec.
+ * Maps to QuotaExceededError and related mint errors.
+ */
+declare class SssMintError extends SSSError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * @spec SssComplianceError — compliance error class required by the SSS spec.
+ * Maps to BlacklistedError and related compliance errors.
+ */
+declare class SssComplianceError extends SSSError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * @spec SssRpcError — network/RPC error class required by the SSS spec.
+ * Maps to TransactionError for network-level failures.
+ */
+declare class SssRpcError extends SSSError {
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * @module presets/sssAcl
+ * @description SSS-ACL preset — a Token ACL (sRFC 37) stablecoin gated by ThawGate. The default for new mints.
+ *
+ * Accounts start frozen (DefaultAccountState) and holders thaw themselves through the ThawGate gate, which checks
+ * the issuer's blacklist/allowlist and, optionally, a SAS KYC credential once per account. Transfers carry no
+ * transfer hook. Blacklist, seize (permanent delegate) and pause (Token-2022 Pausable) work through Token ACL.
+ * After `initialize`, the master authority calls `enable_token_acl` to create the Token ACL config and the policy.
+ */
+
+/**
+ * Default initialization arguments for an SSS-ACL stablecoin.
+ *
+ * @param name - Stablecoin name
+ * @param symbol - Ticker symbol
+ * @param uri - Metadata URI
+ * @param decimals - Decimal places (default: 6)
+ * @returns InitializeArgs configured for SSS-ACL
+ */
+declare function sssAclPreset(name: string, symbol: string, uri: string, decimals?: number): InitializeArgs;
+/**
+ * SSS-ACL feature flags for documentation and validation.
+ */
+declare const SSS_ACL_FEATURES: {
+    readonly mint: true;
+    readonly burn: true;
+    readonly freeze: true;
+    readonly pause: true;
+    readonly roles: true;
+    readonly blacklist: true;
+    readonly seize: true;
+    readonly transferHook: false;
+    readonly permanentDelegate: true;
+    readonly tokenAcl: true;
+    readonly defaultAccountFrozen: true;
+};
+
+/**
+ * @module presets/sssBoth
+ * @description SSS-Both preset — Token ACL gating (see sssAcl) plus the SSS transfer hook on every transfer.
+ *
+ * The hook adds a per-transfer pause and blacklist check on top of the gate's per-account check at thaw. Note:
+ * while the mint is paused, the hook also rejects `seize` (its PauseState check has no seize exception).
+ */
+
+/**
+ * Default initialization arguments for an SSS-Both stablecoin.
+ *
+ * @param name - Stablecoin name
+ * @param symbol - Ticker symbol
+ * @param uri - Metadata URI
+ * @param hookProgramId - The transfer hook program ID
+ * @param decimals - Decimal places (default: 6)
+ * @returns InitializeArgs configured for SSS-Both
+ */
+declare function sssBothPreset(name: string, symbol: string, uri: string, hookProgramId: PublicKey, decimals?: number): InitializeArgs;
+/**
+ * SSS-Both feature flags for documentation and validation.
+ */
+declare const SSS_BOTH_FEATURES: {
+    readonly mint: true;
+    readonly burn: true;
+    readonly freeze: true;
+    readonly pause: true;
+    readonly roles: true;
+    readonly blacklist: true;
+    readonly seize: true;
+    readonly transferHook: true;
+    readonly permanentDelegate: true;
+    readonly tokenAcl: true;
+    readonly defaultAccountFrozen: true;
+};
+
+/**
+ * @module presets/sss1
+ * @description SSS-1 preset configuration — basic stablecoin.
+ *
+ * SSS-1 provides: mint, burn, freeze/thaw, pause/unpause, role management.
+ * No compliance features (blacklist, seize, transfer hook).
+ */
+
+/**
+ * Default initialization arguments for an SSS-1 stablecoin.
+ *
+ * @param name - Stablecoin name
+ * @param symbol - Ticker symbol
+ * @param uri - Metadata URI
+ * @param decimals - Decimal places (default: 6)
+ * @returns InitializeArgs configured for SSS-1
+ */
+declare function sss1Preset(name: string, symbol: string, uri: string, decimals?: number): InitializeArgs;
+/**
+ * SSS-1 feature flags for documentation and validation.
+ */
+declare const SSS1_FEATURES: {
+    readonly mint: true;
+    readonly burn: true;
+    readonly freeze: true;
+    readonly pause: true;
+    readonly roles: true;
+    readonly blacklist: false;
+    readonly seize: false;
+    readonly transferHook: false;
+    readonly permanentDelegate: false;
+};
+
+/**
+ * @module presets/sss2
+ * @description SSS-2 preset configuration — enhanced compliance stablecoin.
+ *
+ * SSS-2 extends SSS-1 with: blacklist, seize (permanent delegate),
+ * transfer hook for real-time compliance, and default-frozen accounts.
+ * The strict hook mode (`ComplianceMode.Hook`): every transfer pays for the hook. New mints default to SSS-ACL.
+ */
+
+/**
+ * Default initialization arguments for an SSS-2 stablecoin.
+ *
+ * @param name - Stablecoin name
+ * @param symbol - Ticker symbol
+ * @param uri - Metadata URI
+ * @param hookProgramId - The transfer hook program ID
+ * @param decimals - Decimal places (default: 6)
+ * @returns InitializeArgs configured for SSS-2
+ */
+declare function sss2Preset(name: string, symbol: string, uri: string, hookProgramId: PublicKey, decimals?: number): InitializeArgs;
+/**
+ * SSS-2 feature flags for documentation and validation.
+ */
+declare const SSS2_FEATURES: {
+    readonly mint: true;
+    readonly burn: true;
+    readonly freeze: true;
+    readonly pause: true;
+    readonly roles: true;
+    readonly blacklist: true;
+    readonly seize: true;
+    readonly transferHook: true;
+    readonly permanentDelegate: true;
+};
+
+/**
+ * @module presets/sss3
+ * @description SSS-3 preset configuration — private stablecoin.
+ *
+ * SSS-3 extends SSS-2 with: confidential transfers (via SPL Token-2022
+ * Confidential Transfer extension), and allowlist-based access control.
+ * Only allowlisted wallets can transact with the token.
+ */
+
+/**
+ * Default initialization arguments for an SSS-3 stablecoin.
+ *
+ * @param name - Stablecoin name
+ * @param symbol - Ticker symbol
+ * @param uri - Metadata URI
+ * @param hookProgramId - The transfer hook program ID
+ * @param decimals - Decimal places (default: 6)
+ * @returns InitializeArgs configured for SSS-3
+ */
+declare function sss3Preset(name: string, symbol: string, uri: string, hookProgramId: PublicKey, decimals?: number): InitializeArgs;
+/**
+ * SSS-3 feature flags for documentation and validation.
+ */
+declare const SSS3_FEATURES: {
+    readonly mint: true;
+    readonly burn: true;
+    readonly freeze: true;
+    readonly pause: true;
+    readonly roles: true;
+    readonly blacklist: true;
+    readonly seize: true;
+    readonly transferHook: true;
+    readonly permanentDelegate: true;
+    readonly confidentialTransfers: true;
+    readonly allowlist: true;
+};
+
+/**
+ * @module pda
+ * @description PDA derivation helpers for the SSS-Token program.
+ *
+ * All PDAs are derived from the mint address for consistent addressing.
+ * Seeds match the on-chain constants.rs exactly.
+ */
+
+/**
+ * Derives the StablecoinConfig PDA address.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findConfigPda(mint: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives the PauseState PDA address.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findPauseStatePda(mint: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives a RoleRecord PDA address.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param holder - The role holder's public key
+ * @param role - The role type
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findRolePda(mint: PublicKey, holder: PublicKey, role: RoleType, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives a MinterQuota PDA address.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param minter - The minter's public key
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findQuotaPda(mint: PublicKey, minter: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives a BlacklistEntry PDA address.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param target - The blacklisted wallet's public key
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findBlacklistPda(mint: PublicKey, target: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives an AllowlistEntry PDA address (`add_to_allowlist_v3`; read by ThawGate AllowOnly / BypassForPdas policies).
+ *
+ * @param mint - The Token-2022 mint address
+ * @param wallet - The allowlisted wallet's public key
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findAllowlistPda(mint: PublicKey, wallet: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives the ReserveAttestation PDA address (S9).
+ *
+ * @param mint - The Token-2022 mint address
+ * @param programId - The SSS-Token program ID
+ * @returns [pda, bump]
+ */
+declare function findReserveAttestationPda(mint: PublicKey, programId: PublicKey): [PublicKey, number];
+/**
+ * Derives the ExtraAccountMetaList PDA for the transfer hook.
+ *
+ * @param mint - The Token-2022 mint address
+ * @param hookProgramId - The transfer hook program ID
+ * @returns [pda, bump]
+ */
+declare function findExtraAccountMetaListPda(mint: PublicKey, hookProgramId: PublicKey): [PublicKey, number];
+
+/**
+ * @module base/token
+ * @description Core token operations — initialize, mint, burn, freeze, thaw, pause, unpause.
+ *
+ * These functions build Anchor instruction transactions.
+ * The caller is responsible for signing and sending.
+ */
+
+/**
+ * Initializes a new stablecoin.
+ *
+ * Creates the Token-2022 mint with configured extensions,
+ * plus StablecoinConfig, PauseState, and MasterAuthority PDAs.
+ *
+ * @param program - The Anchor program instance
+ * @param authority - The authority keypair (becomes MasterAuthority)
+ * @param args - Initialization arguments (use presets for defaults)
+ * @param mintKeypair - Optional mint keypair (generated if not provided)
+ * @returns Transaction result with mint address
+ */
+declare function initialize(program: Program, authority: PublicKey, args: InitializeArgs, mintKeypair?: Keypair): Promise<{
+    instructions: TransactionInstruction[];
+    mint: PublicKey;
+    mintKeypair: Keypair;
+}>;
+/**
+ * Mints tokens to a recipient.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param minter - The minter's public key (must have Minter role)
+ * @param recipient - The recipient's wallet address
+ * @param amount - Amount to mint (raw, not decimal-adjusted)
+ * @returns Transaction instructions
+ */
+declare function mintTokens(program: Program, mint: PublicKey, minter: PublicKey, recipient: PublicKey, amount: BN): Promise<TransactionInstruction[]>;
+/**
+ * Burns tokens from the burner's account.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param burner - The burner's public key (must have Burner role)
+ * @param amount - Amount to burn (raw, not decimal-adjusted)
+ * @returns Transaction instructions
+ */
+declare function burnTokens(program: Program, mint: PublicKey, burner: PublicKey, amount: BN): Promise<TransactionInstruction[]>;
+/**
+ * Freezes a target token account.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param operator - The operator's public key (MasterAuthority or Blacklister)
+ * @param targetTokenAccount - The token account to freeze
+ * @param operatorRole - The role type of the operator
+ * @returns Transaction instructions
+ */
+declare function freezeAccount(program: Program, mint: PublicKey, operator: PublicKey, targetTokenAccount: PublicKey, operatorRole?: RoleType.MasterAuthority | RoleType.Blacklister): Promise<TransactionInstruction[]>;
+/**
+ * Thaws a frozen token account.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param operator - The operator's public key (MasterAuthority or Blacklister)
+ * @param targetTokenAccount - The token account to thaw
+ * @param operatorRole - The role type of the operator
+ * @returns Transaction instructions
+ */
+declare function thawAccount(program: Program, mint: PublicKey, operator: PublicKey, targetTokenAccount: PublicKey, operatorRole?: RoleType.MasterAuthority | RoleType.Blacklister): Promise<TransactionInstruction[]>;
+/**
+ * Pauses all token operations.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param operator - The operator's public key (Pauser or MasterAuthority)
+ * @param operatorRole - The role type of the operator
+ * @returns Transaction instructions
+ */
+declare function pause(program: Program, mint: PublicKey, operator: PublicKey, operatorRole?: RoleType.Pauser | RoleType.MasterAuthority): Promise<TransactionInstruction[]>;
+/**
+ * Resumes all token operations.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param operator - The operator's public key (Pauser or MasterAuthority)
+ * @param operatorRole - The role type of the operator
+ * @returns Transaction instructions
+ */
+declare function unpause(program: Program, mint: PublicKey, operator: PublicKey, operatorRole?: RoleType.Pauser | RoleType.MasterAuthority): Promise<TransactionInstruction[]>;
+
+declare const token_burnTokens: typeof burnTokens;
+declare const token_freezeAccount: typeof freezeAccount;
+declare const token_initialize: typeof initialize;
+declare const token_mintTokens: typeof mintTokens;
+declare const token_pause: typeof pause;
+declare const token_thawAccount: typeof thawAccount;
+declare const token_unpause: typeof unpause;
+declare namespace token {
+  export { token_burnTokens as burnTokens, token_freezeAccount as freezeAccount, token_initialize as initialize, token_mintTokens as mintTokens, token_pause as pause, token_thawAccount as thawAccount, token_unpause as unpause };
+}
+
+/**
+ * @module base/roles
+ * @description Role management operations — update_minter, update_roles, transfer_authority.
+ */
+
+/**
+ * Creates or updates a minter with a quota.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param authority - The MasterAuthority's public key
+ * @param minter - The minter's public key
+ * @param limit - Maximum mint amount per period
+ * @param period - The quota period
+ * @returns Transaction instructions
+ */
+declare function updateMinter(program: Program, mint: PublicKey, authority: PublicKey, minter: PublicKey, limit: BN, period: QuotaPeriod): Promise<TransactionInstruction[]>;
+/**
+ * Creates or updates a role for a given key.
+ *
+ * Cannot grant MasterAuthority — use transferAuthority instead.
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param authority - The MasterAuthority's public key
+ * @param holder - The key to grant/revoke the role for
+ * @param role - The role type (cannot be MasterAuthority)
+ * @param active - Whether to activate or deactivate
+ * @returns Transaction instructions
+ */
+declare function updateRoles(program: Program, mint: PublicKey, authority: PublicKey, holder: PublicKey, role: RoleType, active: boolean): Promise<TransactionInstruction[]>;
+/**
+ * Transfers MasterAuthority to a new key.
+ *
+ * The old authority's role record is deactivated (audit trail).
+ *
+ * @param program - The Anchor program instance
+ * @param mint - The Token-2022 mint address
+ * @param authority - The current MasterAuthority's public key
+ * @param newAuthority - The new MasterAuthority's public key
+ * @returns Transaction instructions
+ */
+declare function transferAuthority(program: Program, mint: PublicKey, authority: PublicKey, newAuthority: PublicKey): Promise<TransactionInstruction[]>;
+
+declare const roles_transferAuthority: typeof transferAuthority;
+declare const roles_updateMinter: typeof updateMinter;
+declare const roles_updateRoles: typeof updateRoles;
+declare namespace roles {
+  export { roles_transferAuthority as transferAuthority, roles_updateMinter as updateMinter, roles_updateRoles as updateRoles };
+}
+
+/**
+ * @module @thawgate/sdk
+ * @description Solana Stablecoin Standard (SSS) TypeScript SDK.
+ *
+ * This package provides a complete TypeScript API for interacting
+ * with SSS stablecoins on Solana: SSS-ACL (Token ACL gated by ThawGate,
+ * the default), SSS-Both (Token ACL + transfer hook), SSS-1 (basic)
+ * and SSS-2 (transfer hook) configurations.
+ *
+ * @example
+ * ```ts
+ * import { SolanaStablecoin, sssAclPreset, SssError } from "@thawgate/sdk";
+ *
+ * const client = SolanaStablecoin.fromConfig({
+ *   rpcUrl: "https://api.devnet.solana.com",
+ * });
+ *
+ * // Initialize a Token ACL stablecoin (then call enable_token_acl as the master authority)
+ * const { instructions, mint } = await client.initialize(
+ *   authority.publicKey,
+ *   sssAclPreset("USD Stablecoin", "USDS", "https://meta.example.com"),
+ * );
+ * ```
+ */
+
+/**
+ * SSS preset configurations.
+ *
+ * Spec-required export: `Presets.SSS_1` and `Presets.SSS_2`.
+ * Each value provides the feature flags for the respective standard. `SSS_ACL` is the default for new mints.
+ *
+ * @example
+ * ```ts
+ * import { Presets } from "@thawgate/sdk";
+ * const hasPermanentDelegate = Presets.SSS_2.permanentDelegate; // true
+ * ```
+ */
+declare const Presets: {
+    /** SSS-ACL (default): Token ACL gated by ThawGate — no transfer hook. */
+    readonly SSS_ACL: {
+        readonly mint: true;
+        readonly burn: true;
+        readonly freeze: true;
+        readonly pause: true;
+        readonly roles: true;
+        readonly blacklist: true;
+        readonly seize: true;
+        readonly transferHook: false;
+        readonly permanentDelegate: true;
+        readonly tokenAcl: true;
+        readonly defaultAccountFrozen: true;
+    };
+    /** SSS-Both: Token ACL + the transfer hook. */
+    readonly SSS_BOTH: {
+        readonly mint: true;
+        readonly burn: true;
+        readonly freeze: true;
+        readonly pause: true;
+        readonly roles: true;
+        readonly blacklist: true;
+        readonly seize: true;
+        readonly transferHook: true;
+        readonly permanentDelegate: true;
+        readonly tokenAcl: true;
+        readonly defaultAccountFrozen: true;
+    };
+    /** SSS-1: Basic stablecoin — no compliance extensions. */
+    readonly SSS_1: {
+        readonly mint: true;
+        readonly burn: true;
+        readonly freeze: true;
+        readonly pause: true;
+        readonly roles: true;
+        readonly blacklist: false;
+        readonly seize: false;
+        readonly transferHook: false;
+        readonly permanentDelegate: false;
+    };
+    /** SSS-2: Compliance stablecoin — with permanent delegate + transfer hook. */
+    readonly SSS_2: {
+        readonly mint: true;
+        readonly burn: true;
+        readonly freeze: true;
+        readonly pause: true;
+        readonly roles: true;
+        readonly blacklist: true;
+        readonly seize: true;
+        readonly transferHook: true;
+        readonly permanentDelegate: true;
+    };
+    /** SSS-3: Private stablecoin — confidential transfers + allowlist. */
+    readonly SSS_3: {
+        readonly mint: true;
+        readonly burn: true;
+        readonly freeze: true;
+        readonly pause: true;
+        readonly roles: true;
+        readonly blacklist: true;
+        readonly seize: true;
+        readonly transferHook: true;
+        readonly permanentDelegate: true;
+        readonly confidentialTransfers: true;
+        readonly allowlist: true;
+    };
+};
+
+export { ABL_GATE_PROGRAM_ID, AccountNotFoundError, type AddToBlacklistArgs, type AllowlistMode, type AuthorityTransferredEvent, AuthorizationError, type BlacklistEntry, BlacklistedError, ComplianceMode, ComplianceModule, ConfigError, type CreateStablecoinOptions, type CreatedStablecoin, type Explanation, FeatureNotEnabledError, type FreezeResult, GateAction, GateClient, type GateClientOptions, type GatePolicy, GateVerdict, type GateWallet, type InitializeArgs, type InitializeStablecoinOptions, type KeypairWallet, MINT_CONFIG_SIZE, type MintConfig, type MinterQuota, type PauseState, type PermissionlessArgs, type PermissionlessKind, type PolicyInput, Presets, PrivacyModule, type ProgramErrorInfo, QuotaExceededError, QuotaPeriod, type ReserveAttestation, ReservesModule, type RoleRecord, RoleType, SAS_PROGRAM_ID, SSS1_FEATURES, SSS2_FEATURES, SSS3_FEATURES, type SSSClientConfig, SSSError, SSSPreset, SSS_ACL_FEATURES, SSS_BOTH_FEATURES, SSS_TOKEN_ERRORS, SSS_TOKEN_PROGRAM_ID, type SetupMintingOptions, SolanaStablecoin, SssComplianceError, SssError, SssInitError, SssMintError, SssRpcError, type StablecoinConfig, type StablecoinInitializedEvent, THAWGATE_GATE_ERRORS, THAWGATE_GATE_PROGRAM_ID, TOKEN_ACL_IX, TOKEN_ACL_PROGRAM_ID, TRANSFER_HOOK_PROGRAM_ID, TokenPausedError, type TokensSeizedEvent, TransactionError, type TransactionOptions, type TransactionResult, type UpdateMinterArgs, type UpdateRolesArgs, decodeMintConfig, fetchMintConfig, findAllowlistPda, findBlacklistPda, findConfigPda, findExtraAccountMetaListPda, findFlagAccountPda, findFreezeExtraMetasPda, findMintConfigPda, findPauseStatePda, findQuotaPda, findReserveAttestationPda, findRolePda, findThawExtraMetasPda, keypairWallet, parseError, permissionlessIx, programError, roles, index as sas, setGatingProgramIx, sss1Preset, sss2Preset, sss3Preset, sssAclPreset, sssBothPreset, toGatePolicyConfig, togglePermissionlessIx, token };