@typesol/cli 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,81 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 0.18.0 — 2026-10-28
+
+The remaining Anchor differences, closed: Anchor's argument structs (Strings, Vecs, Options and enums in Borsh),
+keypair `init` with `space`, `init` of mints with Token-2022 extensions and of token accounts, `Vec<String>`
+arguments, `SystemAccount`, string return values, and the Token-2022 and Token Metadata instructions programs call.
+Closures, list callbacks and more everyday TypeScript; the rest of Bubblegum and Core. 26 of the 46 official
+examples are now full ports. Existing programs keep their layouts and error codes (2018 and 3011 are new, raised only
+by the new `Init<Mint>` and `SystemAccount` checks). Not externally audited (see SECURITY.md).
+
+### Added
+Anchor accounts and arguments:
+- `@layout borsh` structs as whole instruction arguments, return values and events, in Anchor's Borsh bytes (a
+  FixedString is a String, a FixedVec a Vec, an Option one byte when empty). Arguments are checked as Borsh
+  deserialization does, UTF-8 included (102 otherwise). `return vault` returns a whole struct account.
+- `@layout borsh` structs used as arguments, return values or events may hold `string` fields and data enums (with or
+  without strings), as Anchor argument structs do; Borsh accounts may hold data enums without strings.
+- `acct.create(payer, null)` on `Init<T>`: Anchor's `init` of a keypair account (it must sign; 3010 otherwise), and an
+  optional third argument for Anchor's `space = …` on `create` / `createIfNeeded`.
+- Mint extensions on `Init<Mint>`: `mint.create(payer, seeds | null, decimals, authority, freeze, { … })` with
+  transferFee, closeAuthority, defaultAccountState, nonTransferable, interestBearing, permanentDelegate, transferHook,
+  metadataPointer, groupPointer and groupMemberPointer (Anchor's `extensions::…`).
+- `Init<Mint>` / `InitIfNeeded<Mint>` with `mint.create(payer, seeds | null, decimals, mintAuthority, freezeAuthority)`
+  and `Init<TokenAccount>` / `InitIfNeeded<TokenAccount>` (without `Ata<…>`) with `vault.create(payer, seeds | null,
+  mint, authority)`: Anchor's `init` with `mint::` / `token::` constraints, at a PDA of this program or (with `null`) a
+  new keypair account that signs, under SPL Token or Token-2022 (token accounts sized with GetAccountDataSize). The
+  `createIfNeeded` forms check an existing account like Anchor's `init_if_needed` (2014 / 2015 / 2016 / 2017 and the
+  new 2018 ConstraintMintDecimals). The IDL marks keypair-created accounts as signers.
+- `SystemAccount` / `Mut<SystemAccount>`: Anchor's `SystemAccount`, refused with 3011 (AccountNotSystemOwned) when
+  another program owns it.
+- `Vec<string>` instruction arguments (Anchor's `Vec<String>`): `.get(i)`, `.length`, `for … of`, list callbacks,
+  helper parameters, storing into `FixedVec<FixedString<N>, M>`, and re-encoding through `invoke`; each string is
+  checked as UTF-8 on entry (102).
+- Helpers and instructions can return `string` (an instruction's is Borsh String return data).
+- `acct.key` of an `Init<…>` account before it is created (the address is known; Anchor seeds use it that way).
+- `mint.create(…, tokenProgram)` / `vault.create(…, tokenProgram)`: an explicit token program, for instructions that
+  take more than one.
+
+Language:
+- Closures: a local function that reads or writes the enclosing function's variables is expanded where it is called,
+  with the names it was declared with (a block at the call that declares the same name does not change it), struct
+  parameters by reference and `return` leaving the closure. Recursion and storing / returning closures are refused.
+- List callbacks on Vec, FixedArray, FixedVec and Vec arguments: `forEach`, `some`, `every`, `find`, `findIndex`,
+  `reduce`, `includes`, `indexOf`, expanded into loops with the arrow written at the call.
+- Helpers can take function parameters (`f: (x: u64) => u64`): compiled once per named function passed.
+- `do … while` loops (`continue` goes to the test).
+- `x **= n` (the target must not call a function: it is read and written).
+- `switch` on 128-bit integers (the case is picked with comparisons, then switched on as usual, fallthrough included).
+- `?.` on optional accounts (`acct?.field`) and on `Option<struct>` fields (`x.home?.field`): an Option, empty when the
+  account was left out or the option is empty; use it with `??`.
+- `acct!` on optional accounts (fails with 5115 when it was left out), Pubkeys / Hashes in template strings (base58),
+  and data-enum arguments whose variants carry fixed-size structs or arrays.
+- Type parameters standing for fixed-size structs (`pick<Point>(…)`, or taken from struct arguments), and `cond ? a : b`
+  for struct values (places, literals or calls).
+- Growable `Vec<T>` `push` / `pop` / `clear` inside helpers that take the account as `Mut<T>` (with its payer and
+  SystemProgram, as in instructions).
+- `mulDiv` / `mulDivCeil` on u128 through a 256-bit product (all three u128; literals take that type).
+
+CPI:
+- Token-2022 extension instructions: `updateDefaultAccountState`, `updateTransferHook`, `enableRequiredMemoTransfers` /
+  `disableRequiredMemoTransfers`, `updateInterestRate`, `transferCheckedWithFee`, `harvestWithheldTokensToMint`,
+  `withdrawWithheldTokensFromMint`, `setTransferFee`; the Token Metadata interface: `updateMetadataField`,
+  `removeMetadataKey`, `updateMetadataAuthority`, `emitMetadata`; `closeAccount` of a mint; `mintTo` /
+  `initializeMetadata` on a mint created earlier in the instruction; `isTransferring(tokenAccount)` and
+  `transferHookAuthority(mint)`.
+- Metaplex Core plugin values: MasterEdition, VerifiedCreators, Autograph, FreezeExecute, PermanentFreezeExecute, and
+  royalty rule sets (`ruleSet: { programAllowList | programDenyList }`).
+- Bubblegum: `delegateV2`, `freezeV2`, `thawV2`, `setNonTransferableV2`, `updateMetadataV2`, `verifyCreatorV2`,
+  `unverifyCreatorV2`, `setCollectionV2`, and the V1 `transfer`, `burn`, `delegate`. Checked on the real programs with
+  every leaf recomputed: verify → delegate → freeze (a frozen leaf is refused) → thaw → rename, unverify, moving a leaf
+  into a collection, soulbinding a collection's leaf, and a V1 transfer signed by a PDA owner, delegate and burn.
+
+### Fixed
+- Bubblegum leaf fields that may be null at run time (`assetDataHash: Hash | null`, `flags`) are sent as Borsh Options;
+  a null aborted the instruction before.
+
 ## 0.17.0 — 2026-10-28
 
 Anchor's account bytes on request (`@layout borsh`, so a TypeSOL program can take over an Anchor program's accounts

package/README.md

@@ -189,10 +189,10 @@ Runtime failures point back to your source: `Error 6000 Unauthorized (counter.ts
 
 | | |
 | --- | --- |
-| **Accounts** | `Signer`, `Account<T>`, `Mut<T>`, `Init<T>`, `InitIfNeeded<T>` (PDAs and associated token accounts), `Zeroed<T>` (up to 10 MiB), optional accounts (`A \| null`), token accounts and mints, programs, sysvars |
+| **Accounts** | `Signer`, `Account<T>`, `Mut<T>`, `Init<T>`, `InitIfNeeded<T>` (PDAs or keypair accounts, with Anchor's `space`; mints, token accounts and associated token accounts), `Zeroed<T>` (up to 10 MiB), optional accounts (`A \| null`), token accounts and mints, `SystemAccount`, programs, sysvars |
 | **Constraints** | `HasOne`, `Seeds` (also from account fields and under another program; `pdaBump` like `ctx.bumps`), `CloseTo`, `Ata`, `Address`, `Owner`, `Executable`. They are checked before the body runs and recorded in the IDL |
-| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account, `FixedVec` lists anywhere, and Anchor's own byte layout (`@layout borsh`) to take over existing Anchor accounts |
-| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too, arrow functions, generics) across multiple files |
+| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account, `FixedVec` lists anywhere, and Anchor's own byte layout (`@layout borsh`) to take over existing Anchor accounts and to pass, return and emit structs with String / Vec / Option fields as Anchor does |
+| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too, arrow functions, closures, function arguments, generics), list callbacks (`some`, `find`, `reduce`, …) across multiple files |
 | **CPIs** | System, SPL Token, Token-2022 (including extension reads and metadata), ATA, Metaplex Token Metadata, Core, Bubblegum. Generic `invoke` with PDA signing, return data, and typed bindings generated from any Anchor IDL (`typesol cpi`) |
 | **Events** | `emit` (log-based) and `emitCpi` (Anchor `emit_cpi!`, through a self-CPI) |
 | **Crypto & oracles** | `sha256`, `keccak256`, Merkle proofs, Ed25519 and secp256k1 signature checks, Pyth pull oracle, Switchboard |
@@ -306,7 +306,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.17).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.18).** Releases follow the organization's
 [versioning policy](https://github.com/typesol/.github/blob/main/VERSIONING.md); [CHANGELOG.md](CHANGELOG.md) lists every
 change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.

package/dist/clientgen.js

@@ -39,6 +39,7 @@ export const TYPESOL_ERRORS = {
     2015: "ConstraintTokenOwner",
     2016: "ConstraintMintMintAuthority",
     2017: "ConstraintMintFreezeAuthority",
+    2018: "ConstraintMintDecimals",
     2040: "ConstraintDuplicateMutableAccount",
     3000: "AccountDiscriminatorAlreadySet",
     3002: "AccountDiscriminatorMismatch",
@@ -50,6 +51,7 @@ export const TYPESOL_ERRORS = {
     3008: "InvalidProgramId",
     3009: "InvalidProgramExecutable",
     3010: "AccountNotSigner",
+    3011: "AccountNotSystemOwned",
     3012: "AccountNotInitialized",
     3016: "AccountReallocExceedsLimit",
     4102: "InvalidNumericConversion",

package/dist/compiler/analyze.d.ts

@@ -12,7 +12,7 @@ export declare const MAX_CPI_ALLOCATION: number;
 export interface Analysis {
     model: ProgramModel;
     /** A generic helper's instance for these type arguments (analyzed once, then kept in `model.helpers`). */
-    instantiate(g: GenericHelper, typeArgs: ScalarType[]): Helper;
+    instantiate(g: GenericHelper, typeArgs: TypeArg[], fnArgs?: string[]): Helper;
     /** TypeScript's checker: used for narrowing (which variant a data-enum value is in a branch). */
     checker: ts.TypeChecker;
     sourceFile: ts.SourceFile;
@@ -22,11 +22,20 @@ export interface Analysis {
     imports: Map<string, string>;
     reporter: Reporter;
 }
+/** What a generic helper's type parameter stands for: a scalar, or a fixed-size struct. */
+export type TypeArg = ScalarType | {
+    kind: "struct";
+    name: string;
+};
+/** A struct named by a type reference, through the type parameters of a generic helper's instance. */
+export declare function structNameOf(node: ts.TypeNode, scope: Pick<TypeScope, "structArgs">): string | undefined;
 /** What type resolution needs: imports, unit enums, and where to record Option<T> uses. */
 export interface TypeScope {
     imports: Map<string, string>;
     /** Inside a generic helper's instance: type parameter -> the type it stands for. */
     typeArgs?: Map<string, ScalarType>;
+    /** Inside a generic helper's instance: type parameter -> the struct it stands for. */
+    structArgs?: Map<string, string>;
     enums: Map<string, EnumDef>;
     dataEnums?: Map<string, DataEnumDef>;
     options: Map<string, ScalarType | {

package/dist/compiler/analyze.js

@@ -90,6 +90,7 @@ const TYPE_EXPORTS = new Set([
     "SelfProgram",
     "ProgramData",
     "SignerSeeds",
+    "SystemAccount",
 ]);
 /** Largest fixed array a struct may declare, and largest FixedString. */
 const MAX_ARRAY_LEN = 1_000_000;
@@ -99,6 +100,12 @@ export const MAX_ACCOUNT_SIZE = 10 * 1024 * 1024;
 /** sol_set_return_data's limit. */
 export const MAX_RETURN_DATA = 1024;
 export const MAX_CPI_ALLOCATION = 10 * 1024;
+/** A struct named by a type reference, through the type parameters of a generic helper's instance. */
+export function structNameOf(node, scope) {
+    if (!ts.isTypeReferenceNode(node) || !ts.isIdentifier(node.typeName) || node.typeArguments?.length)
+        return undefined;
+    return scope.structArgs?.get(node.typeName.text) ?? node.typeName.text;
+}
 export function snakeCase(name) {
     return name
         .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
@@ -424,23 +431,35 @@ export function analyze(entry) {
         if (h.node.body)
             collectLocals(h.node.body, h.name, h.imports, h.node);
     const localDecls = new Set(locals.map((l) => l.decl));
-    for (const l of locals)
-        reporter.guard(() => checkCaptures(l, localDecls, checker, reporter));
+    // A local function that reads the enclosing function's variables (or calls one that does) is a closure: it is
+    // expanded where it is called, in the enclosing function. The others become helpers of their own.
+    const inline = new Set(locals.filter((l) => captures(l, localDecls, checker)).map((l) => l.decl));
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const l of locals)
+            if (!inline.has(l.decl) && references(l, inline, checker)) {
+                inline.add(l.decl);
+                changed = true;
+            }
+    }
+    const closureDecls = new Map(locals.filter((l) => inline.has(l.decl)).map((l) => [l.decl, l.display]));
     const helpers = new Map();
     const generics = new Map();
     const helperDecls = new Map();
-    for (const fn of [...helperNodes, ...locals]) {
+    for (const fn of [...helperNodes, ...locals.filter((l) => !inline.has(l.decl))]) {
         helperDecls.set(fn.decl, fn.name);
-        if (fn.node.typeParameters?.length) {
+        const fnParams = fn.node.parameters.map((p, i) => (p.type && ts.isFunctionTypeNode(p.type) ? i : -1)).filter((i) => i >= 0);
+        if (fn.node.typeParameters?.length || fnParams.length) {
             reporter.guard(() => {
-                for (const tp of fn.node.typeParameters)
+                for (const tp of fn.node.typeParameters ?? [])
                     if (tp.default)
                         reporter.fail(tp, "type parameters of helpers take no default");
                 generics.set(fn.name, {
                     name: fn.name,
                     display: fn.display,
                     node: fn.node,
-                    typeParams: fn.node.typeParameters.map((t) => t.name.text),
+                    typeParams: (fn.node.typeParameters ?? []).map((t) => t.name.text),
+                    fnParams,
                     imports: fn.imports,
                 });
             });
@@ -451,20 +470,34 @@ export function analyze(entry) {
             helpers.set(h.name, h);
     }
     const instances = new Map();
-    const instantiate = (g, typeArgs) => {
-        const key = `${g.name}__${typeArgs.map(scalarKey).join("_")}`;
+    const instantiate = (g, typeArgs, fnArgs = []) => {
+        const argKey = (t) => (t.kind === "struct" ? `S${t.name}` : scalarKey(t));
+        const key = [g.name, ...typeArgs.map(argKey), ...fnArgs.map((f) => `fn_${f}`)].join("__");
         const done = instances.get(key);
         if (done)
             return done;
-        const bound = new Map(g.typeParams.map((n, i) => [n, typeArgs[i]]));
-        const display = `${g.display}<${typeArgs.map(typeName).join(", ")}>`;
-        const h = analyzeHelper(g.node, key, display, reporter, { ...scopeFor(g.imports), typeArgs: bound }, structs);
+        const bound = new Map();
+        const boundStructs = new Map();
+        g.typeParams.forEach((n, i) => {
+            const t = typeArgs[i];
+            if (t.kind === "struct")
+                boundStructs.set(n, t.name);
+            else
+                bound.set(n, t);
+        });
+        const display = `${g.display}<${[...typeArgs.map((t) => (t.kind === "struct" ? t.name : typeName(t))), ...fnArgs].join(", ")}>`;
+        const h = analyzeHelper(g.node, key, display, reporter, { ...scopeFor(g.imports), typeArgs: bound, structArgs: boundStructs }, structs, new Set(g.fnParams));
         h.typeArgs = bound;
+        h.structArgs = boundStructs;
+        if (g.fnParams.length) {
+            h.fnArgs = new Map(g.fnParams.map((i, k) => [g.node.parameters[i].name.text, fnArgs[k]]));
+            h.fnArgIndexes = g.fnParams;
+        }
         instances.set(key, h);
         helpers.set(key, h);
         return h;
     };
-    reporter.guard(() => checkRecursion([...helperNodes, ...locals], helperDecls, checker, reporter));
+    reporter.guard(() => checkRecursion([...helperNodes, ...locals.filter((l) => !inline.has(l.decl))], helperDecls, checker, reporter));
     const accountStructs = new Set();
     const argStructs = new Set();
     const instructions = [];
@@ -478,26 +511,29 @@ export function analyze(entry) {
         for (const a of ix.args) {
             const seen = new Set();
             collectStructs(a.type, structs, dataEnums, seen);
+            // A @layout borsh struct is decoded as a whole argument; inside lists or enums it would need a fixed size.
+            const whole = a.type.kind === "structRef" ? a.type.struct : undefined;
             for (const s of seen)
-                if (structs.get(s).layout === "borsh")
-                    reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} is @layout borsh, an account layout only`);
+                if (structs.get(s).layout === "borsh" && s !== whole)
+                    reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} is @layout borsh; pass it as a whole argument, not inside a list or enum`);
         }
-        if (ix.returns?.kind === "struct" && structs.get(ix.returns.name).layout === "borsh")
-            reporter.error(fn.node.type ?? fn.node, `${ix.returns.name} is @layout borsh, an account layout only; return another struct`);
-        // Arguments are Borsh: a FixedVec's padded layout is account data only.
+        // Arguments are Borsh: a FixedVec's padded layout is account data only (a @layout borsh struct's FixedVec is a Borsh Vec).
         for (const a of ix.args) {
             const seen = new Set();
             collectStructs(a.type, structs, dataEnums, seen);
             for (const s of seen)
-                if (structs.get(s).fields.some((f) => f.type.kind === "vec" && f.type.cap !== undefined))
+                if (structs.get(s).layout !== "borsh" && structs.get(s).fields.some((f) => f.type.kind === "vec" && f.type.cap !== undefined))
                     reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} holds a FixedVec, which only account data can; pass a Vec<T> argument instead`);
         }
         // A returned struct goes out in its fixed layout, like an argument comes in: it cannot also be a Borsh event.
         if (ix.returns?.kind === "struct")
             collectStructs(ix.returns, structs, dataEnums, argStructs);
         for (const a of ix.accounts)
-            if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded")
+            if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded") {
                 accountStructs.add(a.kind.struct.name);
+                if (a.kind.struct.viewsOnly)
+                    reporter.error(a.node, `${a.kind.struct.name} holds a string (or an enum carrying one), so it is an argument, return value or event; account data uses FixedString<N>`);
+            }
     }
     checkSnakeDuplicates(instructions.map((ix) => ({ name: ix.node.name.text, node: ix.node.name })), "instructions", reporter);
     // emitCpi's event instruction (Anchor's EVENT_IX_TAG) is dispatched before every other instruction.
@@ -530,6 +566,7 @@ export function analyze(entry) {
             helpers,
             generics,
             helperDecls,
+            closureDecls,
             errors,
             errorEnums,
             enums,
@@ -585,7 +622,7 @@ export function resolveArgAggregate(node, scope, structs) {
         if (scalar)
             return scalar;
         if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName) && !t.typeArguments?.length) {
-            const s = structs.get(t.typeName.text);
+            const s = structs.get(structNameOf(t, scope));
             if (s && s.size !== undefined && !s.vec)
                 return { kind: "struct", name: s.name };
         }
@@ -668,6 +705,9 @@ export function resolveValueType(node, scope, allowVec = false) {
         return { kind: "dataEnumArg", name: node.typeName.text };
     if (allowVec && typesolName(node, scope.imports) === "Vec") {
         const elemNode = node.typeArguments?.[0];
+        // Vec<string>: Borsh Vec<String>, read as views of the instruction data.
+        if (elemNode?.kind === ts.SyntaxKind.StringKeyword)
+            return { kind: "vecArg", elem: { kind: "string" } };
         const elem = elemNode && resolveScalarType(elemNode, scope);
         if (elem)
             return { kind: "vecArg", elem };
@@ -935,7 +975,11 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings,
         state.set(s.name, "visiting");
         let total = 0;
         for (const f of s.fields) {
-            const fsz = sizeOf(f.type, s.node);
+            // In a @layout borsh struct a string (or a data enum carrying one) is held as a TS_Str view: a C size, no layout.
+            const view = s.layout === "borsh" && (f.type.kind === "string" || (f.type.kind === "dataEnum" && sizeOf(f.type, s.node) === undefined));
+            if (view)
+                s.viewsOnly = true;
+            const fsz = view ? (f.type.kind === "string" ? 16 : 1 + dataEnums.get(f.type.name).payload) : sizeOf(f.type, s.node);
             total = total === undefined || fsz === undefined ? undefined : total + fsz;
         }
         s.size = total;
@@ -954,19 +998,19 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings,
         reporter.guard(() => visit(s));
     for (const s of structs.values())
         if (s.layout === "borsh")
-            reporter.guard(() => checkBorshLayout(s, structs, reporter));
+            reporter.guard(() => checkBorshLayout(s, structs, dataEnums, reporter));
     for (const e of dataEnums.values())
         reporter.guard(() => sizeOf({ kind: "dataEnum", name: e.name }, e.node));
     return structs;
 }
 const isFunctionNode = (n) => ts.isFunctionDeclaration(n) || ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isMethodDeclaration(n);
-/**
- * A local function becomes a helper of its own, so it can only use its parameters, its own locals, top-level names and
- * other local functions: reading a variable of the enclosing function (a closure) is refused.
- */
-function checkCaptures(l, localDecls, checker, reporter) {
+/** Whether a local function reads a variable or parameter of a function around it (a closure). */
+function captures(l, localDecls, checker) {
     const fn = l.node;
+    let found = false;
     const visit = (n) => {
+        if (found)
+            return;
         if (ts.isIdentifier(n)) {
             const sym = ts.isShorthandPropertyAssignment(n.parent) ? checker.getShorthandAssignmentValueSymbol(n.parent) : checker.getSymbolAtLocation(n);
             for (const d of sym?.declarations ?? []) {
@@ -974,30 +1018,53 @@ function checkCaptures(l, localDecls, checker, reporter) {
                     continue;
                 if (d.getSourceFile() !== fn.getSourceFile() || (d.pos >= fn.pos && d.end <= fn.end))
                     continue;
-                // Declared in some function around this one: a captured variable.
                 for (let p = d.parent; p; p = p.parent)
-                    if (isFunctionNode(p)) {
-                        reporter.fail(n, `${l.display} reads "${n.text}" of the function around it; pass it as a parameter (local functions capture nothing)`);
-                    }
+                    if (isFunctionNode(p))
+                        found = true;
             }
         }
         ts.forEachChild(n, visit);
     };
     if (fn.body)
         visit(fn.body);
+    return found;
+}
+/** Whether a function's body names one of `decls` (a closure it calls). */
+function references(l, decls, checker) {
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(n))
+            for (const d of checker.getSymbolAtLocation(n)?.declarations ?? [])
+                if (decls.has(d))
+                    found = true;
+        ts.forEachChild(n, visit);
+    };
+    if (l.node.body)
+        visit(l.node.body);
+    return found;
 }
 /**
  * A `@layout borsh` struct: its own fields may be FixedString (Borsh String), FixedVec (Borsh Vec) and Option; anything
  * nested must already be Borsh-identical (fixed-size scalars, Pubkeys, enums, arrays and structs of them).
  */
-function checkBorshLayout(s, structs, reporter) {
+function checkBorshLayout(s, structs, dataEnums, reporter) {
     const model = { structs };
     const fixed = (t) => borshIdentical(t, model);
     for (const f of s.fields) {
         const t = f.type;
         const at = s.node.members.find((m) => m.name && ts.isIdentifier(m.name) && m.name.text === f.name) ?? s.node;
-        if (fixed(t) || t.kind === "fstring")
+        if (fixed(t) || t.kind === "fstring" || t.kind === "string")
             continue;
+        if (t.kind === "dataEnum") {
+            // Borsh enum: tag, then the variant's fields; each a fixed-size value or a string.
+            for (const v of dataEnums.get(t.name)?.variants ?? [])
+                for (const vf of v.fields)
+                    if (!fixed(vf.type) && vf.type.kind !== "string")
+                        reporter.fail(at, `${t.name}.${v.name}.${vf.name} in a @layout borsh struct: enum variants hold fixed-size values and strings`);
+            continue;
+        }
         if (t.kind === "vec" && t.cap === undefined)
             reporter.fail(at, "a @layout borsh struct cannot end in a growable Vec<T>; use FixedVec<T, N> (Anchor's #[max_len(N)] Vec)");
         if (t.kind === "vec" && (fixed(t.elem) || t.elem.kind === "fstring"))
@@ -1015,7 +1082,7 @@ function checkBorshLayout(s, structs, reporter) {
                 reporter.error(s.node.name, `${s.name} is @layout borsh, so it is account data only; ${other.name}.${f.name} cannot hold one`);
         }
 }
-function analyzeHelper(fn, name, display, reporter, scope, structs) {
+function analyzeHelper(fn, name, display, reporter, scope, structs, skip = new Set()) {
     if (!fn.body)
         reporter.fail(fn, "helper functions need a body");
     if (fn.asteriskToken)
@@ -1024,16 +1091,23 @@ function analyzeHelper(fn, name, display, reporter, scope, structs) {
         reporter.fail(fn, "helper functions cannot be async");
     if (!fn.type)
         reporter.fail(fn.name ?? fn, "helper functions need an explicit return type (void, an integer, boolean, Pubkey or a struct)");
-    let returns = fn.type.kind === ts.SyntaxKind.VoidKeyword ? undefined : resolveScalarType(fn.type, scope);
+    let returns = fn.type.kind === ts.SyntaxKind.VoidKeyword
+        ? undefined
+        : fn.type.kind === ts.SyntaxKind.StringKeyword
+            ? { kind: "string" }
+            : resolveScalarType(fn.type, scope);
     if (fn.type.kind !== ts.SyntaxKind.VoidKeyword && !returns) {
-        const s = ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments ? structs.get(fn.type.typeName.text) : undefined;
+        const sn = structNameOf(fn.type, scope);
+        const s = sn ? structs.get(sn) : undefined;
         if (s && (s.size === undefined || s.vec))
             reporter.fail(fn.type, `${s.name} has variable-size fields and cannot be returned; return a struct of fixed size`);
         if (!s)
-            reporter.fail(fn.type, "helpers return void, an integer, boolean, Pubkey, a struct or a type parameter");
+            reporter.fail(fn.type, "helpers return void, an integer, boolean, Pubkey, string, a struct or a type parameter");
         returns = { kind: "struct", name: s.name };
     }
-    const params = fn.parameters.map((p) => {
+    const params = fn.parameters
+        .filter((_, i) => !skip.has(i))
+        .map((p) => {
         if (!ts.isIdentifier(p.name) || !p.type || p.initializer || p.questionToken || p.dotDotDotToken)
             reporter.fail(p, "parameters need a plain name and an explicit type");
         // `p_<name>__n` carries a SignerSeeds count: "__" in a name could collide with it.
@@ -1120,7 +1194,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
         reporter.fail(fn, "instructions cannot be async or generators");
     let returns;
     if (fn.type && fn.type.kind !== ts.SyntaxKind.VoidKeyword) {
-        returns = resolveScalarType(fn.type, scope);
+        returns = fn.type.kind === ts.SyntaxKind.StringKeyword ? { kind: "string" } : resolveScalarType(fn.type, scope);
         const s = !returns && ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments
             ? structs.get(fn.type.typeName.text)
             : undefined;
@@ -1133,7 +1207,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
             returns = { kind: "struct", name: s.name };
         }
         if (!returns)
-            reporter.fail(fn.type, "instructions return void, one integer, boolean or Pubkey, or a fixed-size struct (sent as return data)");
+            reporter.fail(fn.type, "instructions return void, one integer, boolean, Pubkey or string, or a fixed-size struct (sent as return data)");
     }
     const accounts = [];
     const args = [];
@@ -1173,7 +1247,8 @@ function analyzeInstruction(fn, reporter, scope, structs) {
             const inner = unwrapConstraints(typeNode, reporter, imports, constraints);
             const kind = resolveAccountKind(inner, reporter, imports, structs);
             if (optional &&
-                (["init", "initIfNeeded", "zeroed", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) || (kind.kind === "token" && kind.init)))
+                (["init", "initIfNeeded", "zeroed", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) ||
+                    ((kind.kind === "token" || kind.kind === "mint") && kind.init)))
                 reporter.fail(p, "Init, InitIfNeeded, Zeroed, PythPriceUpdate, EventAuthority, SelfProgram and ProgramData accounts cannot be optional");
             accounts.push({ name: p.name.text, index: accounts.length, kind, node: p, constraints, ...(optional ? { optional } : {}) });
         });
@@ -1186,10 +1261,11 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     // Constraints refer to other parameters by name: check them now that all are known.
     for (const a of accounts) {
         const c = a.constraints;
-        if (a.kind.kind === "token" && a.kind.init && !c.ata)
-            reporter.fail(a.node, 'Init<TokenAccount> / InitIfNeeded<TokenAccount> create associated token accounts: wrap them in Ata<…, "owner", "mint">');
-        if (a.kind.kind === "token" && a.kind.init && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
+        if (a.kind.kind === "token" && a.kind.init && c.ata && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
             reporter.fail(a.node, "an associated token account created here is checked against Ata<…>'s owner and mint; drop HasOne/Seeds/Address/Owner/Executable");
+        // Token accounts and mints created in the body are checked there (seeds, mint, authorities).
+        if ((a.kind.kind === "token" || a.kind.kind === "mint") && a.kind.init && !c.ata && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
+            reporter.fail(a.node, `${a.name}.create(...) takes the seeds, mint and authorities; drop HasOne/Seeds/Address/Owner/Executable`);
         if (!c.hasOne.length && !c.seeds && !c.closeTo && !c.ata)
             continue;
         const struct = a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "initIfNeeded" || a.kind.kind === "zeroed" ? a.kind.struct : undefined;
@@ -1381,6 +1457,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
         // Any account (helpers that accept every kind, e.g. generated CPI helpers).
         case "AccountMeta":
             return { kind: "info", mut: false };
+        case "SystemAccount":
+            return { kind: "info", mut: false, systemOwned: true };
         case "TokenAccount":
             return { kind: "token", mut: false };
         case "Mint":
@@ -1438,9 +1516,11 @@ function resolveAccountKind(node, reporter, imports, structs) {
         case "Init": {
             if (typesolName(inner(), imports) === "TokenAccount")
                 return { kind: "token", mut: true, init: "create" };
+            if (typesolName(inner(), imports) === "Mint")
+                return { kind: "mint", mut: true, init: "create" };
             const s = structOf(inner());
             if (!s)
-                reporter.fail(node, "Init<T> needs a struct declared in this program");
+                reporter.fail(node, "Init<T> needs a struct declared in this program, TokenAccount or Mint");
             if (s.size + 8 > MAX_CPI_ALLOCATION)
                 reporter.fail(node, `${s.name} needs ${s.size + 8} bytes but a program can create at most ${MAX_CPI_ALLOCATION} through Init<T>; have the client allocate it and take it as Zeroed<${s.name}>`);
             return { kind: "init", struct: s };
@@ -1448,6 +1528,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
         case "InitIfNeeded": {
             if (typesolName(inner(), imports) === "TokenAccount")
                 return { kind: "token", mut: true, init: "ifNeeded" };
+            if (typesolName(inner(), imports) === "Mint")
+                return { kind: "mint", mut: true, init: "ifNeeded" };
             const s = structOf(inner());
             if (!s)
                 reporter.fail(node, "InitIfNeeded<T> needs a struct declared in this program");
@@ -1475,6 +1557,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
                 return { kind: "signer", mut: true };
             if (innerName === "AccountInfo" || innerName === "AccountMeta")
                 return { kind: "info", mut: true };
+            if (innerName === "SystemAccount")
+                return { kind: "info", mut: true, systemOwned: true };
             if (innerName === "TokenAccount")
                 return { kind: "token", mut: true };
             if (innerName === "Mint")

package/dist/compiler/emit/base.d.ts

@@ -2,7 +2,7 @@ import ts from "typescript";
 import { type Analysis, type TypeScope } from "../analyze.js";
 import type { Reporter } from "../diagnostics.js";
 import { type AccountParam, type Helper, type IdlSeed, type Instruction, type ProgramModel, type ValueType } from "../model.js";
-import { type Value, type Local, type EmitOptions } from "./shared.js";
+import { type Value, type Ref, type Local, type Closure, type EmitOptions } from "./shared.js";
 /**
  * State of one function being lowered, and the primitives every layer uses: emitting lines, temporaries,
  * scopes, evaluation-order snapshots and account lookups.
@@ -24,6 +24,17 @@ export declare abstract class EmitterBase {
     protected readonly pendingInit: Set<string>;
     /** Bump temporaries from create()/createIfNeeded(), for `acct.pdaBump`. */
     protected readonly bumps: Map<string, string>;
+    /** Closures being expanded, innermost last: a `return` inside one assigns `result` and jumps to `label`. */
+    protected inlineFrames: {
+        label: string;
+        result: string;
+        type?: ValueType;
+        declAt: number;
+        pad: string;
+        node: ts.Node;
+    }[];
+    /** Closures being expanded (a closure calling itself cannot be expanded). */
+    protected readonly inlining: Set<ts.Node>;
     /** Enclosing loops, innermost last; each has a `continue` label. */
     protected readonly loops: string[];
     protected readonly ix: Instruction | undefined;
@@ -39,6 +50,14 @@ export declare abstract class EmitterBase {
     constructor(analysis: Analysis, target: Instruction | Helper, opts?: EmitOptions);
     /** The helper a call runs: a function, a const arrow function (top-level or local), or a generic one's instance. */
     protected helperOf(node: ts.CallExpression): Helper | undefined;
+    /**
+     * The functions passed for a helper's function parameters: named functions only (a helper, or a local function that
+     * captures nothing). A closure can only run where it is declared, so it cannot be passed.
+     */
+    private fnArgsOf;
+    /** A struct written as a type argument (`pick<Point>(…)`). */
+    private structArg;
+    private fixedStruct;
     /** A generic call's type arguments: written out (`max<u64>(a, b)`), or the types of the arguments in `T` positions. */
     private typeArgsOf;
     protected line(s: string): void;
@@ -59,11 +78,17 @@ export declare abstract class EmitterBase {
     protected block(fn: () => void): void;
     protected fail(node: ts.Node, message: string): never;
     protected exportName(node: ts.Expression): string | undefined;
+    /**
+     * `acct!.field` on an optional account: the same access without `!` (using the account checks that it was passed,
+     * failing with 3020 otherwise). Returns undefined for anything else.
+     */
+    protected withoutBang(node: ts.Expression): ts.PropertyAccessExpression | undefined;
     protected accountParam(node: ts.Expression, what: string): AccountParam;
     protected assertUsable(a: AccountParam, node: ts.Node): void;
     protected abstract expect(v: Value, want: ValueType | undefined, node: ts.Node): Value;
     protected abstract literal(value: bigint, type: ValueType, node: ts.Node): Value;
     protected abstract expr(node: ts.Expression, hint?: ValueType): Value;
+    protected abstract ref(node: ts.Expression): Ref | undefined;
     protected abstract call(node: ts.CallExpression, topLevel: boolean): Value | undefined;
     protected abstract isRemaining(node: ts.Expression): boolean;
     protected abstract handle(node: ts.Expression): string | undefined;
@@ -75,6 +100,7 @@ export declare abstract class EmitterBase {
     protected abstract recordPda(account: AccountParam, idl: IdlSeed[] | undefined): void;
     protected abstract create(node: ts.CallExpression, target: AccountParam, topLevel: boolean, ifNeeded?: boolean): Value;
     protected abstract createAta(node: ts.CallExpression, target: AccountParam, topLevel: boolean): Value | undefined;
+    protected abstract createToken(node: ts.CallExpression, target: AccountParam, topLevel: boolean): Value;
     protected abstract systemTransfer(node: ts.CallExpression): undefined;
     protected abstract createAccount(node: ts.CallExpression, system: AccountParam): undefined;
     protected abstract tokenOp(node: ts.CallExpression, program: AccountParam, method: string): undefined;
@@ -88,4 +114,6 @@ export declare abstract class EmitterBase {
         program: string;
     }): undefined;
     protected abstract epilogue(): string[];
+    protected abstract expandClosure(c: Closure, args: readonly ts.Expression[], node: ts.Node): Value | undefined;
+    protected abstract listMethod(node: ts.CallExpression, method: string): Value | undefined;
 }