@typesol/cli 0.17.0 → 0.19.0

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

@@ -12,12 +12,36 @@ export declare abstract class ExpressionEmitter extends StorageEmitter {
      * check is a backstop: an empty option aborts with 5108.
      */
     protected unwrap(v: Value, node: ts.Node): Value;
+    /**
+     * `acct?.field` on an optional account, `x.home?.field` on an Option<struct> place: the field as an Option, empty
+     * when the account was left out / the option is empty. (A method call through `?.` is not supported.)
+     */
+    protected optionalChain(node: ts.PropertyAccessExpression): Value;
     protected literal(value: bigint, type: ValueType, node: ts.Node): Value;
     protected expr(node: ts.Expression, hint?: ValueType): Value;
     protected property(node: ts.PropertyAccessExpression): Value;
     /** Whether TypeScript sees this expression as a string (decides `+` between concatenation and arithmetic). */
     protected looksLikeString(node: ts.Expression): boolean;
     /** A string view of a string, integer or boolean (for concatenation and templates). */
+    /**
+     * A template literal's pieces in order, text known at compile time folded in: all text (`text`), or a C array of
+     * TS_Str (`arr`, `n` entries). When a later piece runs statements, earlier pieces that view account text are copied
+     * first, as JS reads them then.
+     */
+    protected templatePieces(node: ts.TemplateExpression): {
+        text: string;
+        arr?: undefined;
+        n?: undefined;
+    } | {
+        text?: undefined;
+        arr: string;
+        n: number;
+    };
+    /**
+     * The text of `${e}` when it is known at compile time: a string literal or constant, a non-negative integer
+     * literal, a boolean literal, or a Pubkey constant (its base58). Undefined otherwise.
+     */
+    protected constantText(e: ts.Expression): string | undefined;
     protected toText(node: ts.Expression): string;
     /** C statement writing the decimal text of an integer into the TS_Str `out`. */
     protected textOfInt(name: IntName, c: string, out: string): string;

package/dist/compiler/emit/expressions.js

@@ -1,6 +1,7 @@
 import ts from "typescript";
+import { base58 } from "../../keys.js";
 import { calleeName, resolveValueType } from "../analyze.js";
-import { INT_INFO, unsignedC, sameType, typeName } from "../model.js";
+import { INT_INFO, unsignedC, optionKey, sameType, typeName } from "../model.js";
 import { U64, U8, I64, BOOL, PUBKEY, STRING, HASH, cString, intLiteral, scalarStorageC, optC, valueC, vecCount } from "./shared.js";
 import { StorageEmitter } from "./storage.js";
 /**
@@ -52,6 +53,52 @@ export class ExpressionEmitter extends StorageEmitter {
             return { c: `(${t}.v != 0)`, type: inner };
         return { c: `${t}.v`, type: inner };
     }
+    /**
+     * `acct?.field` on an optional account, `x.home?.field` on an Option<struct> place: the field as an Option, empty
+     * when the account was left out / the option is empty. (A method call through `?.` is not supported.)
+     */
+    optionalChain(node) {
+        const base = node.expression;
+        const optAccount = ts.isIdentifier(base) ? this.accounts.get(base.text) : undefined;
+        let present;
+        if (optAccount?.optional)
+            present = `a_${optAccount.name} != NULL`;
+        else {
+            const r = this.ref(base);
+            if (!r || r.type.kind !== "option" || r.type.inner.kind !== "struct")
+                this.fail(node, "?. works on optional accounts and Option<struct> values (other values are never null)");
+            present = `${r.lv}.some`;
+        }
+        // The same access without `?.`, lowered where the base is known to be there.
+        const f = ts.factory;
+        const plain = f.createPropertyAccessExpression(base, node.name);
+        ts.setTextRange(plain, node);
+        plain.parent = node.parent;
+        const t = this.tmp("oc");
+        const declAt = this.lines.length;
+        this.line(`/* ${t} */`);
+        let inner;
+        this.line(`if (${present}) {`);
+        this.block(() => {
+            const v = this.expr(plain);
+            const typed = v.literal !== undefined ? this.literal(v.literal, U64, node) : v;
+            if (typed.type.kind === "option") {
+                inner = typed.type.inner;
+                this.line(`ts_memcpy(&${t}, &${typed.c}, sizeof(${t}));`);
+                return;
+            }
+            if (typed.type.kind !== "int" && typed.type.kind !== "bool" && typed.type.kind !== "pubkey" && typed.type.kind !== "enum")
+                this.fail(node, `?. gives an Option, so the field must be an integer, boolean, Pubkey or enum, not ${typeName(typed.type)}`);
+            inner = typed.type;
+            this.line(`${t}.some = 1;`);
+            this.line(inner.kind === "pubkey" ? `${t}.v = *(${typed.c});` : `${t}.v = ${typed.c};`);
+        });
+        this.line(`}`);
+        const scalar = inner;
+        this.model.options.set(optionKey(scalar), scalar);
+        this.lines[declAt] = `${"  ".repeat(this.indent)}${optC(scalar)} ${t};\n${"  ".repeat(this.indent)}ts_memzero(&${t}, sizeof(${t}));`;
+        return { c: t, type: { kind: "option", inner: scalar } };
+    }
     literal(value, type, node) {
         if (type.kind !== "int")
             this.fail(node, `expected ${typeName(type)}, got an integer literal`);
@@ -84,6 +131,11 @@ export class ExpressionEmitter extends StorageEmitter {
                 this.fail(node, "! works on Option values; check optional accounts with `x !== null`");
             return this.unwrap(v, node);
         }
+        if (ts.isPropertyAccessExpression(node) && node.questionDotToken)
+            return this.optionalChain(node);
+        const unbanged = this.withoutBang(node);
+        if (unbanged)
+            return this.expr(unbanged, hint);
         this.noOptionalChain(node);
         if (ts.isBigIntLiteral(node)) {
             const value = BigInt(node.text.slice(0, -1).replace(/_/g, ""));
@@ -100,22 +152,14 @@ export class ExpressionEmitter extends StorageEmitter {
             return { c: `ts_str((const uint8_t *)${cString(node.text)}, ${len})`, type: STRING, stringLiteral: node.text };
         }
         if (ts.isTemplateExpression(node)) {
-            // `a${x}b${y}c` -> concatenations on the heap
-            let acc = this.tmp("tpl");
-            const head = node.head.text;
-            this.line(`TS_Str ${acc} = ts_str((const uint8_t *)${cString(head)}, ${Buffer.byteLength(head, "utf8")});`);
-            for (const span of node.templateSpans) {
-                for (const piece of [
-                    this.toText(span.expression),
-                    `ts_str((const uint8_t *)${cString(span.literal.text)}, ${Buffer.byteLength(span.literal.text, "utf8")})`,
-                ]) {
-                    const next = this.tmp("tpl");
-                    this.line(`TS_Str ${next};`);
-                    this.line(`TS_TRY(ts_str_concat(${acc}, ${piece}, &${next}));`);
-                    acc = next;
-                }
-            }
-            return { c: acc, type: STRING };
+            // `a${x}b${y}c`: one join on the heap (or a literal when every piece is known at compile time).
+            const pieces = this.templatePieces(node);
+            if (pieces.text !== undefined)
+                return { c: `ts_str((const uint8_t *)${cString(pieces.text)}, ${Buffer.byteLength(pieces.text, "utf8")})`, type: STRING, stringLiteral: pieces.text };
+            const t = this.tmp("tpl");
+            this.line(`TS_Str ${t};`);
+            this.line(`TS_TRY(ts_str_join(${pieces.arr}, ${pieces.n}, &${t}));`);
+            return { c: t, type: STRING };
         }
         if (node.kind === ts.SyntaxKind.NullKeyword)
             return { c: "", type: BOOL, isNull: true };
@@ -126,6 +170,8 @@ export class ExpressionEmitter extends StorageEmitter {
         if (ts.isIdentifier(node)) {
             const l = this.lookup(node.text);
             if (l) {
+                if (l.closure)
+                    this.fail(node, `"${node.text}" is a function: TypeSOL functions are called (${node.text}(…)), not passed around or stored`);
                 if (l.type.kind === "array")
                     this.fail(node, `"${node.text}" is an array; use .get(i)`);
                 if (l.type.kind === "remaining")
@@ -248,8 +294,11 @@ export class ExpressionEmitter extends StorageEmitter {
         if (ts.isIdentifier(node.expression)) {
             const a = this.accounts.get(node.expression.text);
             if (a) {
-                this.assertUsable(a, node);
                 const v = `a_${a.name}`;
+                // The address is known before an Init account is created (Anchor seeds use `mint.key()` that way).
+                if (field === "key" && !a.optional)
+                    return { c: `&${v}->key`, type: PUBKEY };
+                this.assertUsable(a, node);
                 if (field === "key")
                     return { c: `&${v}->key`, type: PUBKEY };
                 if (field === "lamports")
@@ -374,6 +423,68 @@ export class ExpressionEmitter extends StorageEmitter {
         return isText(this.checker.getTypeAtLocation(node));
     }
     /** A string view of a string, integer or boolean (for concatenation and templates). */
+    /**
+     * A template literal's pieces in order, text known at compile time folded in: all text (`text`), or a C array of
+     * TS_Str (`arr`, `n` entries). When a later piece runs statements, earlier pieces that view account text are copied
+     * first, as JS reads them then.
+     */
+    templatePieces(node) {
+        const parts = [];
+        const lit = (text) => {
+            if (!text)
+                return;
+            const last = parts.at(-1);
+            if (last?.text !== undefined)
+                last.text += text;
+            else
+                parts.push({ text });
+        };
+        lit(node.head.text);
+        for (const span of node.templateSpans) {
+            const known = this.constantText(span.expression);
+            if (known !== undefined)
+                lit(known);
+            else {
+                const mark = this.lines.length;
+                const c = this.toText(span.expression);
+                for (const p of parts)
+                    if (p.c !== undefined)
+                        p.c = this.settle({ c: p.c, type: STRING }, mark).c;
+                parts.push({ c });
+            }
+            lit(span.literal.text);
+        }
+        if (parts.every((p) => p.text !== undefined))
+            return { text: parts.map((p) => p.text).join("") };
+        const strOf = (text) => `ts_str((const uint8_t *)${cString(text)}, ${Buffer.byteLength(text, "utf8")})`;
+        const arr = this.tmp("parts");
+        this.line(`TS_Str ${arr}[${parts.length}] = {${parts.map((p) => (p.text !== undefined ? strOf(p.text) : p.c)).join(", ")}};`);
+        return { arr, n: parts.length };
+    }
+    /**
+     * The text of `${e}` when it is known at compile time: a string literal or constant, a non-negative integer
+     * literal, a boolean literal, or a Pubkey constant (its base58). Undefined otherwise.
+     */
+    constantText(e) {
+        if (ts.isParenthesizedExpression(e))
+            return this.constantText(e.expression);
+        if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e))
+            return e.text;
+        if (e.kind === ts.SyntaxKind.TrueKeyword)
+            return "true";
+        if (e.kind === ts.SyntaxKind.FalseKeyword)
+            return "false";
+        if (ts.isBigIntLiteral(e))
+            return BigInt(e.text.slice(0, -1).replace(/_/g, "")).toString();
+        if (ts.isIdentifier(e) && !this.lookup(e.text)) {
+            const k = this.model.constants.get(e.text);
+            if (k && typeof k.value === "string")
+                return k.value;
+            if (k && typeof k.value === "object")
+                return base58(Uint8Array.from(k.value.pubkey));
+        }
+        return undefined;
+    }
     toText(node) {
         const v = this.expr(node);
         if (v.type.kind === "string")
@@ -404,7 +515,14 @@ export class ExpressionEmitter extends StorageEmitter {
             this.line(this.textOfInt(typed.type.name, typed.c, t));
             return t;
         }
-        this.fail(node, `only strings, integers and booleans can be joined into text, not ${typeName(typed.type)}`);
+        if (typed.type.kind === "pubkey") {
+            // A Pubkey (or Hash) as base58, as Rust's `{}` prints it.
+            const t = this.tmp("b58");
+            this.line(`TS_Str ${t};`);
+            this.line(`TS_TRY(ts_base58_32((const uint8_t *)(${typed.c}), &${t}));`);
+            return t;
+        }
+        this.fail(node, `only strings, integers, booleans and Pubkeys can be joined into text, not ${typeName(typed.type)}`);
     }
     /** C statement writing the decimal text of an integer into the TS_Str `out`. */
     textOfInt(name, c, out) {

package/dist/compiler/emit/function.js

@@ -2,7 +2,7 @@ import ts from "typescript";
 import { snakeCase } from "../analyze.js";
 import { decodeAddress } from "../../keys.js";
 import { INT_INFO, isScalar, isWritable, scalarSize, typeName, } from "../model.js";
-import { borshMinSize } from "./borsh.js";
+import { borshIdentical, borshMinSize } from "./borsh.js";
 import { MAX_ACCOUNTS, ATA_PROGRAM_BYTES, cBytes, cString, optC, fieldC, storageDecl, helperSignature } from "./shared.js";
 import { StatementEmitter } from "./statements.js";
 /**
@@ -46,8 +46,11 @@ export class FunctionEmitter extends StatementEmitter {
             // A token account created by this instruction is checked where it is created (create/createIfNeeded).
             if (k.kind === "token" && !k.init)
                 head.push(`  TS_TRY(ts_check_token_account(${v}));`);
-            if (k.kind === "mint")
+            // A mint created by this instruction is checked where it is created.
+            if (k.kind === "mint" && !k.init)
                 head.push(`  TS_TRY(ts_check_mint(${v}));`);
+            if (k.kind === "info" && k.systemOwned)
+                head.push(`  if (!ts_key_eq(&${v}->owner, &TS_SYSTEM_PROGRAM_ID)) TS_FAIL(TS_ERR_NOT_SYSTEM_OWNED, "TypeSOL: ${a.name} must be owned by the System Program");`);
             if (k.kind === "system")
                 head.push(`  TS_TRY(ts_check_address(${v}, &TS_SYSTEM_PROGRAM_ID));`);
             if (k.kind === "instructionsSysvar")
@@ -96,7 +99,7 @@ export class FunctionEmitter extends StatementEmitter {
                 const S = k.struct.name;
                 head.push(`  TSS_${S} *d_${a.name} = NULL;`, `  TS_TRY(ts_alloc(sizeof(TSS_${S}), (uint8_t **)&d_${a.name}));`);
                 if (k.kind === "account")
-                    head.push(`  TS_TRY(ts_unpack_${S}(${v}->data + 8, ${v}->data_len - 8, d_${a.name}));`);
+                    head.push(`  TS_TRY(ts_unpack_${S}(${v}->data + 8, ${v}->data_len - 8, d_${a.name}, NULL));`);
             }
             else if (k.kind === "account" || k.kind === "init" || k.kind === "zeroed" || k.kind === "initIfNeeded") {
                 head.push(`  TSS_${k.struct.name} *d_${a.name} = (TSS_${k.struct.name} *)(${v}->data + 8);`);
@@ -200,6 +203,17 @@ export class FunctionEmitter extends StatementEmitter {
                 }
                 head.push(`  }`);
             }
+            else if (a.type.kind === "vecArg" && a.type.elem.kind === "string") {
+                // Borsh Vec<String>: u32 count, then each string's u32 length and UTF-8 bytes. Kept as views of the
+                // instruction data in a heap array of TS_Str (each string at least 4 bytes, so the count is bounded first).
+                const v = `arg_${a.name}`;
+                const items = `vs_${a.name}`;
+                const i = `vi_${a.name}`;
+                need("4");
+                head.push(`  TS_VecArg ${v};`, `  ${v}.len = (uint32_t)ts_read_le(${at}, 4);`, `  off += 4;`);
+                need(`(uint64_t)${v}.len * 4`);
+                head.push(`  TS_Str *${items};`, `  TS_TRY(ts_alloc((uint64_t)${v}.len * sizeof(TS_Str), (uint8_t **)&${items}));`, `  for (uint64_t ${i} = 0; ${i} < ${v}.len; ${i}++) {`, `    if (params->data_len < off + 4) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: instruction data too short");`, `    uint32_t n = (uint32_t)ts_read_le(params->data + off, 4);`, `    off += 4;`, `    if (params->data_len - off < n) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: instruction data too short");`, `    if (!ts_utf8_valid(params->data + off, n)) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: invalid UTF-8 in a string argument");`, `    ${items}[${i}] = ts_str(params->data + off, n);`, `    off += n;`, `  }`, `  ${v}.ptr = (const uint8_t *)${items};`);
+            }
             else if (a.type.kind === "vecArg") {
                 const elem = a.type.elem;
                 const size = this.fieldBytes(elem);
@@ -215,6 +229,21 @@ export class FunctionEmitter extends StatementEmitter {
                         head.push(`  for (uint64_t ${i} = 0; ${i} < arg_${a.name}.len; ${i}++) {`, ...checks, `  }`);
                 }
             }
+            else if (a.type.kind === "structRef" && this.model.structs.get(a.type.struct).layout === "borsh") {
+                // A @layout borsh struct: Borsh-decoded into its fixed-layout struct, as its accounts are.
+                const S = a.type.struct;
+                const v = `arg_${a.name}`;
+                const used = `used_${a.name}`;
+                head.push(`  TSS_${S} *${v};`, `  TS_TRY(ts_alloc(sizeof(TSS_${S}), (uint8_t **)&${v}));`, `  uint64_t ${used} = 0;`, `  if (ts_unpack_${S}(${at}, params->data_len - off, ${v}, &${used}) != SUCCESS) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: invalid ${S} argument");`, `  off += ${used};`);
+                // Strings from outside are checked as UTF-8 (account data was checked when it was written).
+                for (const f of this.model.structs.get(S).fields) {
+                    const bad = `TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: invalid UTF-8 in a string argument")`;
+                    if (f.type.kind === "fstring")
+                        head.push(`  if (!ts_utf8_valid(${v}->${f.name}.bytes, ${v}->${f.name}.len)) ${bad};`);
+                    else if (f.type.kind === "vec" && f.type.elem.kind === "fstring")
+                        head.push(`  for (uint64_t i = 0; i < ${v}->${f.name}.len; i++)`, `    if (!ts_utf8_valid(${v}->${f.name}.items[i].bytes, ${v}->${f.name}.items[i].len)) ${bad};`);
+                }
+            }
             else if (a.type.kind === "structRef" || a.type.kind === "arrayArg") {
                 // Fixed layouts are Borsh-identical: copy to the heap, then check bools, enums, options and strings.
                 const v = `arg_${a.name}`;
@@ -245,8 +274,17 @@ export class FunctionEmitter extends StatementEmitter {
                             head.push(`    if (!ts_utf8_valid(${lv}.ptr, ${lv}.len)) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: invalid UTF-8 in a string argument");`);
                             continue;
                         }
+                        if (!isScalar(f.type) && borshIdentical(f.type, this.model)) {
+                            // A struct or array whose Borsh bytes are its fixed layout: copied, then checked (bools, enums).
+                            const lv = `${v}.v.${variant.name}.${f.name}`;
+                            const size = this.fieldBytes(f.type);
+                            head.push(`    if (params->data_len < off + ${size}) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: instruction data too short");`);
+                            head.push(`    ts_memcpy(&${lv}, params->data + off, ${size});`, `    off += ${size};`);
+                            head.push(...this.validation(lv, f.type, "    "));
+                            continue;
+                        }
                         if (!isScalar(f.type))
-                            this.reporter.fail(a.node, `${e.name}.${variant.name}.${f.name}: enum arguments carry integers, booleans, Pubkeys, enums and strings`);
+                            this.reporter.fail(a.node, `${e.name}.${variant.name}.${f.name}: enum arguments carry integers, booleans, Pubkeys, enums, strings and fixed-size structs and arrays of those`);
                         const size = scalarSize(f.type);
                         head.push(`    if (params->data_len < off + ${size}) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: instruction data too short");`);
                         head.push(`    ts_memcpy(&${v}.v.${variant.name}.${f.name}, params->data + off, ${size});`, `    off += ${size};`);
@@ -284,7 +322,14 @@ export class FunctionEmitter extends StatementEmitter {
             this.reporter.guard(() => this.statement(stmt, true));
         for (const name of this.pendingInit) {
             const k = this.accounts.get(name).kind;
-            const how = k.kind === "token" ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer)` : `${name}.create(payer, seeds)`;
+            const a = this.accounts.get(name);
+            const how = k.kind === "token" && a.constraints.ata
+                ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer)`
+                : k.kind === "token"
+                    ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer, seeds | null, mint, authority)`
+                    : k.kind === "mint"
+                        ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer, seeds | null, decimals, authority, freezeAuthority | null)`
+                        : `${name}.create(payer, seeds)`;
             this.reporter.error(this.accounts.get(name).node, `Init account "${name}" is never created; call ${how}`);
         }
         const end = ix.returns
@@ -303,7 +348,7 @@ export class FunctionEmitter extends StatementEmitter {
             .map((a) => {
             const v = `a_${a.name}`;
             const S = a.kind.struct.name;
-            return `if (${a.optional ? `${v} != NULL && ` : ""}${v}->data_len >= 8 && ts_key_eq(&${v}->owner, params->program_id)) TS_TRY(ts_pack_${S}(d_${a.name}, ${v}->data + 8, ${v}->data_len - 8));`;
+            return `if (${a.optional ? `${v} != NULL && ` : ""}${v}->data_len >= 8 && ts_key_eq(&${v}->owner, params->program_id)) TS_TRY(ts_pack_${S}(d_${a.name}, ${v}->data + 8, ${v}->data_len - 8, NULL));`;
         });
         return [
             ...packs,
@@ -326,15 +371,17 @@ export class FunctionEmitter extends StatementEmitter {
             const k = a.kind.kind;
             if (c.hasOne.length && k !== "account" && k !== "token" && k !== "mint")
                 this.reporter.fail(a.node, "HasOne applies to existing accounts (Account<T> / Mut<T>), TokenAccount and Mint");
-            for (const f of c.hasOne) {
+            for (const entry of c.hasOne) {
+                // "field=param" (TokenOf / MintOf) or a field checked against the parameter of the same name (HasOne).
+                const [f, p = f] = entry.split("=");
                 if (k === "token")
                     out.push(f === "mint"
-                        ? `  if (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${f}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${f}");`
-                        : `  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${f}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${f}");`);
+                        ? `  if (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${p}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${p}");`
+                        : `  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${p}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${p}");`);
                 else if (k === "mint") {
                     const at = f === "mintAuthority" ? 0 : 46;
                     const code = f === "mintAuthority" ? "TS_ERR_MINT_AUTHORITY" : "TS_ERR_FREEZE_AUTHORITY";
-                    out.push(`  if (ts_read_le(a_${a.name}->data + ${at}, 4) != 1 || !ts_key_eq((const SolPubkey *)(a_${a.name}->data + ${at + 4}), &a_${f}->key)) TS_FAIL(${code}, "TypeSOL: ${f} is not the ${f} of ${a.name}");`);
+                    out.push(`  if (ts_read_le(a_${a.name}->data + ${at}, 4) != 1 || !ts_key_eq((const SolPubkey *)(a_${a.name}->data + ${at + 4}), &a_${p}->key)) TS_FAIL(${code}, "TypeSOL: ${p} is not the ${f} of ${a.name}");`);
                 }
                 else
                     out.push(`  if (!ts_key_eq(&d_${a.name}->${f}, &a_${f}->key)) TS_FAIL(TS_ERR_CONSTRAINT, "TypeSOL: ${a.name}.${f} must be the ${f} account");`);

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

@@ -65,6 +65,14 @@ export interface Local {
     /** For struct / data-enum references: the storage paths they alias (e.g. "book.asks[]"), and the declaration. */
     paths?: string[];
     decl?: ts.VariableDeclaration;
+    /** A local closure (`const f = (…) => …` reading the enclosing function's variables), expanded where it is called. */
+    closure?: Closure;
+}
+/** A closure and the scopes it was declared in (its free names resolve there, wherever it is called). */
+export interface Closure {
+    node: ts.ArrowFunction | ts.FunctionExpression;
+    name: string;
+    scopes: Map<string, Local>[];
 }
 export declare const cBytes: (bytes: number[]) => string;
 /** C expressions that nothing in a TypeSOL expression can change: temporaries, locals, arguments, account keys, constants. */

package/dist/compiler/emit/shared.js

@@ -185,6 +185,9 @@ export function helperSignature(h) {
             params.push(`TsAccount *a_${p.name}`);
             if (p.account.kind === "account" && p.account.struct.layout === "borsh")
                 params.push(`TSS_${p.account.struct.name} *d_${p.name}`);
+            // A writable account with a growable Vec: its length at instruction entry, for push / pop / clear.
+            if (p.account.kind === "account" && p.account.mut && p.account.struct.vec)
+                params.push(`uint64_t entry_${p.name}`);
         }
         else if (p.type.kind === "signerSeeds")
             params.push(`const SolSignerSeed *p_${p.name}`, `int p_${p.name}__n`);
@@ -196,7 +199,7 @@ export function helperSignature(h) {
             params.push(`${valueC(p.type)} p_${p.name}`);
     }
     if (h.returns)
-        params.push(h.returns.kind === "struct" ? `TSS_${h.returns.name} *ret` : `${scalarC(h.returns)} *ret`);
+        params.push(h.returns.kind === "struct" ? `TSS_${h.returns.name} *ret` : h.returns.kind === "string" ? `TS_Str *ret` : `${scalarC(h.returns)} *ret`);
     return `static uint64_t fn_${h.name}(${params.join(", ")})`;
 }
 /** C typedef name of a FixedVec<T, N>: `{ uint32_t len; T items[N]; }`. */

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

@@ -1,4 +1,5 @@
 import ts from "typescript";
+import { type Value, type Closure } from "./shared.js";
 import { CpiEmitter } from "./cpi.js";
 /**
  * Statements: variables, assignment, control flow and return.
@@ -23,6 +24,26 @@ export declare abstract class StatementEmitter extends CpiEmitter {
      * inside the loop so its checked-arithmetic temporaries are recomputed every iteration.
      */
     protected loop(cond: ts.Expression | undefined, body: ts.Statement, step: ts.Expression | undefined): void;
+    /**
+     * Expand a closure where it is called: the arguments are evaluated here, in order, into the parameters (scalars,
+     * Pubkeys and strings by value, structs by reference, as JS passes objects); the body then runs with the names it
+     * was declared with, so a block around the call that declares the same name does not change what it reads, and
+     * writes to captured `let`s are seen by the enclosing function. Returns the result (undefined for no value).
+     */
+    protected expandClosure(c: Closure, args: readonly ts.Expression[], node: ts.Node): Value | undefined;
+    /**
+     * `xs.forEach / some / every / find / findIndex / reduce / includes / indexOf` on a Vec, FixedArray, FixedVec or Vec
+     * argument: an index loop (the length read each step, as `for … of`), the callback (an arrow written at the call)
+     * expanded with each element as `xs.get(i)` gives it (structs by reference) and, if it takes one, the index.
+     * `find` gives an Option of the element (scalar elements), `findIndex` / `indexOf` an i64 (-1 when absent).
+     */
+    protected listMethod(node: ts.CallExpression, method: string): Value | undefined;
+    /** `return` inside an expanded closure: the value goes to the closure's result, then past its body. */
+    protected closureReturn(stmt: ts.ReturnStatement, frame: (typeof this.inlineFrames)[number]): void;
+    /** Store a closure's result (fixing its type on the first one) and jump past the rest of its body. */
+    protected closureResult(value: Value, at: ts.Expression, frame: (typeof this.inlineFrames)[number]): void;
+    /** `do { … } while (cond)`: the body once, then the test; `continue` goes to the test. */
+    protected doLoop(stmt: ts.DoStatement): void;
     protected body(stmt: ts.Statement): void;
     protected variable(list: ts.VariableDeclarationList, topLevel?: boolean): void;
     /**