@typesol/cli 0.15.0 → 0.17.0

package/dist/compiler/analyze.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CompileError, Reporter } from "./diagnostics.js";
 import { decodeAddress } from "../keys.js";
-import { optionKey, INT_INFO, INT_NAMES, scalarKey, isScalar, scalarSize, } from "./model.js";
+import { borshIdentical } from "./emit/borsh.js";
+import { optionKey, INT_INFO, INT_NAMES, scalarKey, fixedVecName, isScalar, scalarSize, typeName, } from "./model.js";
 export const LIB_PATH = fileURLToPath(new URL("../../lib/typesol.d.ts", import.meta.url));
 /** Names a struct field may not use because account parameters already expose them. */
 const RESERVED_FIELDS = new Set(["key", "lamports", "dataLen", "create", "equals", "get", "set", "length", "isSigner", "isWritable", "pdaBump"]);
@@ -17,7 +18,7 @@ const C_RESERVED = new Set([
     ..."NULL SUCCESS HEAP_LENGTH HEAP_START_ADDRESS MAX_PERMITTED_DATA_INCREASE MAX_RETURN_DATA MAX_SEED_LENGTH_EXCEEDED INVALID_SEEDS SIZE_PUBKEY memcpy memset strlen static_assert offsetof sol_log_64".split(" "),
 ]);
 /** Why a name cannot be used as a C member, or undefined when it can. */
-function cNameProblem(name) {
+export function cNameProblem(name) {
     if (name.includes("__") || name.startsWith("_"))
         return `"${name}": names starting with "_" or containing "__" are reserved for generated code`;
     if (name.includes("$"))
@@ -57,6 +58,7 @@ const TYPE_EXPORTS = new Set([
     "TokenInterface",
     "FixedArray",
     "FixedString",
+    "FixedVec",
     "Program",
     "UncheckedProgram",
     "CpiAccount",
@@ -94,6 +96,8 @@ const MAX_ARRAY_LEN = 1_000_000;
 const MAX_STRING_CAP = 10_240;
 /** Solana's account size limit, and what a program can allocate itself through a CPI (Init<T>). */
 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;
 export function snakeCase(name) {
     return name
@@ -223,7 +227,7 @@ export function analyze(entry) {
     const isExported = (n) => ts.canHaveModifiers(n) && (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
     const declare = (name, file) => {
         // These prefixes name the IDL types TypeSOL generates for FixedString<N>, Option and data enums in account data.
-        if (/^(FixedString\d|FixedOption_|FixedEnum_)/.test(name.text))
+        if (/^(FixedString\d|FixedVec\d|FixedOption_|FixedEnum_)/.test(name.text))
             reporter.fail(name, `"${name.text}" is reserved for IDL types TypeSOL generates; pick another name`);
         const prev = declared.get(name.text);
         if (prev)
@@ -311,7 +315,8 @@ export function analyze(entry) {
                     else {
                         if (stmt.name)
                             declare(stmt.name, file);
-                        helperNodes.push({ node: stmt, imports });
+                        if (stmt.name)
+                            helperNodes.push({ node: stmt, name: stmt.name.text, display: stmt.name.text, decl: stmt, imports });
                     }
                 }
                 else if (ts.isVariableStatement(stmt)) {
@@ -322,6 +327,14 @@ export function analyze(entry) {
                         if (!ts.isIdentifier(d.name) || !d.initializer)
                             reporter.fail(d, "declare const NAME = literal");
                         const init = d.initializer;
+                        // `const f = (…): T => …` / `const f = function (…) {…}`: a helper.
+                        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+                            if (isEntry && isExported(stmt))
+                                reporter.fail(d.name, "instructions are function declarations: export function name(…)");
+                            declare(d.name, file);
+                            helperNodes.push({ node: init, name: d.name.text, display: d.name.text, decl: d, imports });
+                            continue;
+                        }
                         let value;
                         if (ts.isCallExpression(init) && ts.isIdentifier(init.expression) && imports.get(init.expression.text) === "pubkey") {
                             const arg = init.arguments[0];
@@ -356,6 +369,7 @@ export function analyze(entry) {
         }
     }
     const fstrings = new Set();
+    const fixedVecs = new Map();
     const scopeFor = (imports) => ({ imports, enums, options, dataEnums });
     for (const c of pendingConstTypes) {
         reporter.guard(() => {
@@ -370,14 +384,87 @@ export function analyze(entry) {
             c.def.type = t;
         });
     }
-    const structs = analyzeStructs(interfaces, aliases, dataEnums, reporter, scopeFor, fstrings);
+    const structs = analyzeStructs(interfaces, aliases, dataEnums, reporter, scopeFor, fstrings, fixedVecs);
+    const checker = program.getTypeChecker();
+    // Local `const f = (…) => …` in any function body (and in those local functions): lifted to helpers.
+    const locals = [];
+    const taken = new Set();
+    const collectLocals = (body, outer, imports, fn) => {
+        const generic = !!fn.typeParameters?.length;
+        const visit = (n) => {
+            if (ts.isVariableDeclaration(n) && n.initializer && (ts.isArrowFunction(n.initializer) || ts.isFunctionExpression(n.initializer))) {
+                reporter.guard(() => {
+                    if (!ts.isIdentifier(n.name))
+                        reporter.fail(n.name, "name local functions: const f = (…) => …");
+                    if (generic)
+                        reporter.fail(n, "local functions inside a generic helper are not supported; declare this one at the top level");
+                    if (!(n.parent.flags & ts.NodeFlags.Const) || !ts.isVariableStatement(n.parent.parent))
+                        reporter.fail(n, "declare local functions with const: const f = (…) => …");
+                    if (n.name.text.includes("__") || n.name.text.includes("$"))
+                        reporter.fail(n.name, `"${n.name.text}": "__" and "$" are reserved in names`);
+                    let name = `${outer}__${n.name.text}`;
+                    for (let i = 2; taken.has(name); i++)
+                        name = `${outer}__${n.name.text}__${i}`;
+                    taken.add(name);
+                    const src = { node: n.initializer, name, display: n.name.text, decl: n, imports, outer: fn };
+                    locals.push(src);
+                    if (src.node.body)
+                        collectLocals(src.node.body, name, imports, src.node);
+                });
+                return;
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(body);
+    };
+    for (const f of functions)
+        if (f.node.body && f.node.name)
+            collectLocals(f.node.body, f.node.name.text, f.imports, f.node);
+    for (const h of [...helperNodes])
+        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));
     const helpers = new Map();
-    for (const fn of helperNodes) {
-        const h = reporter.guard(() => analyzeHelper(fn.node, reporter, scopeFor(fn.imports), structs));
+    const generics = new Map();
+    const helperDecls = new Map();
+    for (const fn of [...helperNodes, ...locals]) {
+        helperDecls.set(fn.decl, fn.name);
+        if (fn.node.typeParameters?.length) {
+            reporter.guard(() => {
+                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),
+                    imports: fn.imports,
+                });
+            });
+            continue;
+        }
+        const h = reporter.guard(() => analyzeHelper(fn.node, fn.name, fn.display, reporter, scopeFor(fn.imports), structs));
         if (h)
             helpers.set(h.name, h);
     }
-    reporter.guard(() => checkRecursion(helpers, reporter));
+    const instances = new Map();
+    const instantiate = (g, typeArgs) => {
+        const key = `${g.name}__${typeArgs.map(scalarKey).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);
+        h.typeArgs = bound;
+        instances.set(key, h);
+        helpers.set(key, h);
+        return h;
+    };
+    reporter.guard(() => checkRecursion([...helperNodes, ...locals], helperDecls, checker, reporter));
     const accountStructs = new Set();
     const argStructs = new Set();
     const instructions = [];
@@ -388,6 +475,26 @@ export function analyze(entry) {
         instructions.push(ix);
         for (const a of ix.args)
             collectStructs(a.type, structs, dataEnums, argStructs);
+        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).layout === "borsh")
+                    reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} is @layout borsh, an account layout only`);
+        }
+        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.
+        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))
+                    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")
                 accountStructs.add(a.kind.struct.name);
@@ -421,6 +528,8 @@ export function analyze(entry) {
             structs,
             instructions,
             helpers,
+            generics,
+            helperDecls,
             errors,
             errorEnums,
             enums,
@@ -431,12 +540,14 @@ export function analyze(entry) {
             accountStructs,
             argStructs,
             fstrings,
+            fixedVecs,
         },
         sourceFile,
         files: programFiles(program, entryPath).map((f) => f.fileName),
         imports: entryImports,
         reporter,
-        checker: program.getTypeChecker(),
+        checker,
+        instantiate,
     };
 }
 /** Every struct an argument type contains (transitively), for IDL layout decisions. */
@@ -510,6 +621,11 @@ export function typesolName(node, imports) {
 export function resolveScalarType(node, scope) {
     if (node.kind === ts.SyntaxKind.BooleanKeyword)
         return { kind: "bool" };
+    if (scope.typeArgs && ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && !node.typeArguments) {
+        const t = scope.typeArgs.get(node.typeName.text);
+        if (t)
+            return t;
+    }
     const n = typesolName(node, scope.imports);
     if (n && INT_NAMES.includes(n))
         return { kind: "int", name: n };
@@ -567,7 +683,7 @@ function numericLiteralArg(node) {
  * Resolve every exported interface. Field types may name other interfaces, so names are
  * collected first; sizes are computed after, rejecting cycles.
  */
-function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings) {
+function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings, fixedVecs) {
     const names = new Set(items.map((d) => d.decl.name.text));
     const enumNames = new Set(aliases.map((a) => a.decl.name.text));
     const structs = new Map();
@@ -623,6 +739,19 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 reporter.fail(targs[1], `array length must be 1..${MAX_ARRAY_LEN}`);
             return { kind: "array", elem, len };
         }
+        if (ext === "FixedVec") {
+            if (!targs[0])
+                reporter.fail(node, "FixedVec<T, N> needs an element type");
+            const elem = fieldType(targs[0]);
+            if (elem.kind === "string" || elem.kind === "vec")
+                reporter.fail(targs[0], "FixedVec elements must have a fixed size (use FixedString<N>)");
+            const cap = numericLiteralArg(targs[1]);
+            if (cap === undefined || !Number.isInteger(cap) || cap < 1 || cap > MAX_ARRAY_LEN)
+                reporter.fail(node, `FixedVec<T, N> needs a literal capacity 1..${MAX_ARRAY_LEN}, e.g. FixedVec<u64, 16>`);
+            const t = { kind: "vec", elem, cap };
+            fixedVecs.set(fixedVecName(t), t);
+            return t;
+        }
         if (ext === "FixedString") {
             const cap = numericLiteralArg(targs[0]);
             if (cap === undefined || !Number.isInteger(cap) || cap < 1 || cap > MAX_STRING_CAP)
@@ -632,7 +761,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
         }
         if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && names.has(node.typeName.text) && !targs.length)
             return { kind: "struct", name: node.typeName.text };
-        reporter.fail(node, "field type must be an integer, boolean, Pubkey, FixedArray<T, N>, FixedString<N>, string (events only) or another struct");
+        reporter.fail(node, "field type must be an integer, boolean, Pubkey, FixedArray<T, N>, FixedString<N>, FixedVec<T, N>, Vec<T> (last), string (events only) or another struct");
     };
     for (const { decl, imports: fileImports } of items) {
         scope = scopeFor(fileImports);
@@ -653,12 +782,17 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 if (problem)
                     reporter.fail(m.name, problem);
                 const type = fieldType(m.type);
-                if (type.kind === "vec" && m !== decl.members[decl.members.length - 1])
-                    reporter.fail(m, "a Vec<T> field must be the last field of the struct (its length changes the account size)");
+                if (type.kind === "vec" && type.cap === undefined && m !== decl.members[decl.members.length - 1])
+                    reporter.fail(m, "a Vec<T> field must be the last field of the struct (its length changes the account size); use FixedVec<T, N> for a list of at most N elsewhere");
                 fields.push({ name, type });
             }
             checkSnakeDuplicates(decl.members.map((m) => ({ name: m.name.text, node: m })), "fields", reporter);
             const name = decl.name.text;
+            // `/** @layout borsh */`: stored as Anchor stores it.
+            const layoutTag = ts.getJSDocTags(decl).find((t) => t.tagName.text === "layout");
+            const layoutText = typeof layoutTag?.comment === "string" ? layoutTag.comment.trim() : undefined;
+            if (layoutTag && layoutText !== "borsh" && layoutText !== "fixed")
+                reporter.fail(layoutTag, "@layout is borsh (Anchor's account bytes) or fixed (the default)");
             structs.set(name, {
                 name,
                 fields,
@@ -666,6 +800,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 accountDiscriminator: discriminator(`account:${name}`),
                 eventDiscriminator: discriminator(`event:${name}`),
                 node: decl,
+                layout: layoutText === "borsh" ? "borsh" : "fixed",
             });
         });
     }
@@ -696,8 +831,8 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                     if (problem)
                         reporter.fail(p.name, problem);
                     const t = fieldType(p.type);
-                    if (t.kind === "string" || t.kind === "vec")
-                        reporter.fail(p.type, "variant fields must have a fixed size (use FixedString<N>)");
+                    if (t.kind === "vec")
+                        reporter.fail(p.type, "variant fields must have a fixed size (a Vec cannot be one; use FixedArray<T, N>)");
                     fields.push({ name: p.name.text, type: t });
                 }
                 if (!vname || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(vname))
@@ -734,15 +869,41 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                     reporter.fail(at, `data enum ${e.name} contains itself`);
                 if (state.get(`enum:${e.name}`) !== "done") {
                     state.set(`enum:${e.name}`, "visiting");
+                    // A string field is a TS_Str view (16 bytes) in the C payload and makes the enum variable-size.
+                    const fieldSize = (f) => {
+                        if (f.kind === "string") {
+                            e.variable = true;
+                            return 16;
+                        }
+                        if (f.kind === "dataEnum") {
+                            const inner = dataEnums.get(f.name);
+                            const size = sizeOf(f, e.node);
+                            if (inner?.variable) {
+                                e.variable = true;
+                                return 1 + inner.payload;
+                            }
+                            return size;
+                        }
+                        return sizeOf(f, e.node);
+                    };
                     for (const v of e.variants)
-                        v.size = v.fields.reduce((sum, f) => sum + sizeOf(f.type, e.node), 0);
+                        v.size = v.fields.reduce((sum, f) => sum + fieldSize(f.type), 0);
                     e.payload = Math.max(0, ...e.variants.map((v) => v.size));
                     state.set(`enum:${e.name}`, "done");
                 }
+                // Variable enums have no fixed layout: a struct holding one is event-only, like one holding a string.
+                if (e.variable)
+                    return undefined;
                 return 1 + e.payload;
             }
-            case "vec":
-                return 4; // the u32 length; elements live past the fixed part
+            case "vec": {
+                if (t.cap === undefined)
+                    return 4; // the u32 length; elements live past the fixed part
+                const e = sizeOf(t.elem, at);
+                if (e === undefined)
+                    reporter.fail(at, "FixedVec elements must have a fixed size");
+                return 4 + e * t.cap;
+            }
             case "string":
                 return undefined;
             case "fstring":
@@ -781,7 +942,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
         if (total !== undefined && total + 8 > MAX_ACCOUNT_SIZE)
             reporter.fail(s.node.name, `${s.name} is ${total + 8} bytes with its discriminator; Solana accounts are at most ${MAX_ACCOUNT_SIZE} bytes`);
         const last = s.fields.at(-1);
-        if (last?.type.kind === "vec") {
+        if (last?.type.kind === "vec" && last.type.cap === undefined) {
             const elemSize = sizeOf(last.type.elem, s.node);
             if (elemSize === undefined)
                 reporter.fail(s.node, "Vec elements must have a fixed size");
@@ -791,20 +952,87 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
     };
     for (const s of structs.values())
         reporter.guard(() => visit(s));
+    for (const s of structs.values())
+        if (s.layout === "borsh")
+            reporter.guard(() => checkBorshLayout(s, structs, reporter));
     for (const e of dataEnums.values())
         reporter.guard(() => sizeOf({ kind: "dataEnum", name: e.name }, e.node));
     return structs;
 }
-function analyzeHelper(fn, reporter, scope, structs) {
-    if (!fn.name || !fn.body)
-        reporter.fail(fn, "helper functions need a name and a body");
-    if (fn.typeParameters?.length || fn.asteriskToken)
-        reporter.fail(fn, "helper functions cannot be generic or generators");
+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) {
+    const fn = l.node;
+    const visit = (n) => {
+        if (ts.isIdentifier(n)) {
+            const sym = ts.isShorthandPropertyAssignment(n.parent) ? checker.getShorthandAssignmentValueSymbol(n.parent) : checker.getSymbolAtLocation(n);
+            for (const d of sym?.declarations ?? []) {
+                if (!(ts.isVariableDeclaration(d) || ts.isParameter(d) || ts.isBindingElement(d)) || localDecls.has(d))
+                    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)`);
+                    }
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    if (fn.body)
+        visit(fn.body);
+}
+/**
+ * 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) {
+    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")
+            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"))
+            continue;
+        if (t.kind === "option" && fixed(t.inner))
+            continue;
+        if (t.kind === "struct" && structs.get(t.name)?.layout === "borsh")
+            reporter.fail(at, `${t.name} is @layout borsh itself: only account structs take a layout; nest a struct without one`);
+        reporter.fail(at, `${typeName(t)} in a @layout borsh struct: its fields may be fixed-size values, FixedString<N>, FixedVec<T, N> (of those or of FixedString) and Option<T>; nested structs and lists hold fixed-size values only`);
+    }
+    for (const other of structs.values())
+        for (const f of other.fields) {
+            const inner = f.type.kind === "array" || f.type.kind === "vec" ? f.type.elem : f.type.kind === "option" ? f.type.inner : f.type;
+            if (inner.kind === "struct" && inner.name === s.name)
+                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) {
+    if (!fn.body)
+        reporter.fail(fn, "helper functions need a body");
+    if (fn.asteriskToken)
+        reporter.fail(fn, "helper functions cannot be generators");
+    if ((ts.getModifiers(fn) ?? []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword))
+        reporter.fail(fn, "helper functions cannot be async");
     if (!fn.type)
-        reporter.fail(fn.name, "helper functions need an explicit return type (void, an integer, boolean or Pubkey)");
-    const returns = fn.type.kind === ts.SyntaxKind.VoidKeyword ? undefined : resolveScalarType(fn.type, scope);
-    if (fn.type.kind !== ts.SyntaxKind.VoidKeyword && !returns)
-        reporter.fail(fn.type, "helpers return void, an integer, boolean or Pubkey");
+        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);
+    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;
+        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");
+        returns = { kind: "struct", name: s.name };
+    }
     const params = fn.parameters.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");
@@ -825,16 +1053,43 @@ function analyzeHelper(fn, reporter, scope, structs) {
             reporter.fail(p.type, "helpers take accounts that exist: create Init/InitIfNeeded/Zeroed accounts in the instruction, then pass them as Mut<T>");
         return { name: p.name.text, type: { kind: "account" }, account, node: p };
     });
-    return { name: fn.name.text, params, returns, node: fn, imports: scope.imports };
+    return { name, display, params, returns, node: fn, statements: bodyStatements(fn, !returns), imports: scope.imports };
+}
+/** A function's statements; an arrow's expression body is a `return expr;` (or `expr;` when it returns void). */
+function bodyStatements(fn, isVoid) {
+    const body = fn.body;
+    if (ts.isBlock(body))
+        return body.statements;
+    const f = ts.factory;
+    const stmt = isVoid ? f.createExpressionStatement(body) : f.createReturnStatement(body);
+    ts.setTextRange(stmt, body);
+    stmt.parent = fn;
+    return [stmt];
+}
+/** The helper (or generic) a call's callee names: a local function by its declaration, others by name. */
+export function calleeName(callee, decls, checker) {
+    let sym = checker.getSymbolAtLocation(callee);
+    if (sym && sym.flags & ts.SymbolFlags.Alias)
+        sym = checker.getAliasedSymbol(sym);
+    for (const d of sym?.declarations ?? []) {
+        const name = decls.get(d);
+        if (name)
+            return name;
+    }
+    return undefined;
 }
 /** Helpers may call each other, but not recursively: SBF has a small fixed call depth. */
-function checkRecursion(helpers, reporter) {
+function checkRecursion(sources, decls, checker, reporter) {
     const calls = new Map();
-    for (const h of helpers.values()) {
+    const byName = new Map(sources.map((s) => [s.name, s]));
+    for (const h of sources) {
         const out = [];
         const visit = (n) => {
-            if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) && helpers.has(n.expression.text))
-                out.push(n.expression.text);
+            if (ts.isCallExpression(n) && ts.isIdentifier(n.expression)) {
+                const c = calleeName(n.expression, decls, checker);
+                if (c)
+                    out.push(c);
+            }
             ts.forEachChild(n, visit);
         };
         visit(h.node.body);
@@ -844,14 +1099,15 @@ function checkRecursion(helpers, reporter) {
     const walk = (name, path) => {
         if (state.get(name) === "done")
             return;
+        const src = byName.get(name);
         if (state.get(name) === "visiting")
-            reporter.fail(helpers.get(name).node.name, `recursion is not supported: ${[...path, name].join(" -> ")}`);
+            reporter.fail(src.node.name ?? src.node, `recursion is not supported: ${[...path, name].map((n) => byName.get(n).display).join(" -> ")}`);
         state.set(name, "visiting");
         for (const c of calls.get(name) ?? [])
             walk(c, [...path, name]);
         state.set(name, "done");
     };
-    for (const name of helpers.keys())
+    for (const name of byName.keys())
         walk(name, []);
 }
 function analyzeInstruction(fn, reporter, scope, structs) {
@@ -865,8 +1121,19 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     let returns;
     if (fn.type && fn.type.kind !== ts.SyntaxKind.VoidKeyword) {
         returns = 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;
+        if (s) {
+            if (s.size === undefined || s.vec)
+                reporter.fail(fn.type, `${s.name} has variable-size fields and cannot be return data`);
+            // The runtime caps return data at 1024 bytes.
+            if (s.size > MAX_RETURN_DATA)
+                reporter.fail(fn.type, `${s.name} is ${s.size} bytes; return data holds at most ${MAX_RETURN_DATA}`);
+            returns = { kind: "struct", name: s.name };
+        }
         if (!returns)
-            reporter.fail(fn.type, "instructions return void or one integer, boolean or Pubkey (sent as return data)");
+            reporter.fail(fn.type, "instructions return void, one integer, boolean or Pubkey, or a fixed-size struct (sent as return data)");
     }
     const accounts = [];
     const args = [];
@@ -996,7 +1263,8 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     const pushes = (() => {
         let found = false;
         const visit = (n) => {
-            if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "push")
+            // Vec.push(value, payer) grows the account; FixedVec.push(value) does not.
+            if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "push" && n.arguments.length === 2)
                 found = true;
             ts.forEachChild(n, visit);
         };
@@ -1193,6 +1461,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
                 reporter.fail(node, "Zeroed<T> needs a struct declared in this program");
             if (s.vec)
                 reporter.fail(node, `${s.name} ends in a Vec; Zeroed<T> is for fixed-size (large) accounts`);
+            if (s.layout === "borsh")
+                reporter.fail(node, `${s.name} is @layout borsh; Zeroed<T> reads large accounts in place, so it takes fixed layouts only`);
             return { kind: "zeroed", struct: s };
         }
         case "Mut": {

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

@@ -30,10 +30,17 @@ export declare abstract class EmitterBase {
     protected readonly helper: Helper | undefined;
     protected readonly scope: TypeScope;
     protected readonly checker: ts.TypeChecker;
+    protected readonly analysis: Analysis;
+    /** Calls already resolved to a helper (a generic one's instance is found by probing its arguments). */
+    private readonly calleeCache;
     /** `file.ts:line` of the statement being lowered. */
     protected where: string | undefined;
     protected readonly profile: boolean;
     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;
+    /** 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;
     /** `file.ts:line` of a node, for messages. */
     protected location(node: ts.Node): string;