flags.ts

/**
 * Issuer control flags & trustline authorization (Class 2).
 *
 * These are the RIGHT side of the control spectrum — every lever that lets the issuer gate, freeze,
 * or renounce. Note *where* the authority lives: `setIssuerFlags` and `setTrustLineFlags` are sourced
 * from the ISSUER account. The issuer's power is exactly the power to source these ops.
 */
import {
  Operation,
  AuthRequiredFlag,
  AuthRevocableFlag,
  AuthClawbackEnabledFlag,
} from "@stellar/stellar-sdk";
import type { Asset } from "@stellar/stellar-sdk";
import type { IssuerFlags } from "../lib/config.js";

/**
 * Set the issuer account's control flags from the config booleans (sourced from the issuer).
 *
 * IMPORTANT ORDERING (decisions.md D11): this must run BEFORE any distribution. Clawback only binds
 * trustlines opened *after* AUTH_CLAWBACK_ENABLED is set — distribute first and the tokens are
 * permanently un-clawbackable. Also note AUTH_CLAWBACK_ENABLED requires AUTH_REVOCABLE.
 */
export function setIssuerFlags(flags: IssuerFlags) {
  let setFlags = 0;
  if (flags.authRequired) setFlags |= AuthRequiredFlag;
  if (flags.authRevocable) setFlags |= AuthRevocableFlag;
  if (flags.clawbackEnabled) setFlags |= AuthClawbackEnabledFlag;
  // `setFlags` is a combined bitmask (a valid runtime value); the SDK types the field as the
  // single-flag `AuthFlag` union, so cast the options object to the accepted parameter type.
  type SetOptionsArgs = Parameters<typeof Operation.setOptions>[0];
  return Operation.setOptions({ setFlags } as SetOptionsArgs);
}

/** Authorize a holder's trustline (needed under AUTH_REQUIRED before they can receive). Issuer-sourced. */
export function authorizeTrustline(trustor: string, asset: Asset) {
  return Operation.setTrustLineFlags({ trustor, asset, flags: { authorized: true } });
}

/**
 * Freeze a holder's trustline: they can no longer send or receive the asset. Issuer-sourced; requires
 * AUTH_REVOCABLE. Pass `maintainLiabilities: true` to keep their existing DEX offers alive while frozen.
 */
export function freezeTrustline(trustor: string, asset: Asset, maintainLiabilities = false) {
  return Operation.setTrustLineFlags({
    trustor,
    asset,
    flags: maintainLiabilities
      ? { authorized: false, authorizedToMaintainLiabilities: true }
      : { authorized: false, authorizedToMaintainLiabilities: false },
  });
}

/** Thaw a previously frozen trustline (alias of authorize). */
export function thawTrustline(trustor: string, asset: Asset) {
  return authorizeTrustline(trustor, asset);
}

/**
 * Lock the issuer: set its master key weight to 0, so it can never sign again. Supply becomes
 * credibly FIXED. **Irreversible** — there is no unlock (decisions.md D14). Issuer-sourced.
 */
export function lockIssuer() {
  return Operation.setOptions({ masterWeight: 0 });
}