@typesol/cli 0.15.0 → 0.17.0

package/dist/compiler/emit/base.js

@@ -1,4 +1,6 @@
 import ts from "typescript";
+import { calleeName, resolveScalarType } from "../analyze.js";
+import { isScalar, } from "../model.js";
 import { isStable, cString, valueC } from "./shared.js";
 /**
  * State of one function being lowered, and the primitives every layer uses: emitting lines, temporaries,
@@ -27,6 +29,9 @@ export class EmitterBase {
     helper;
     scope;
     checker;
+    analysis;
+    /** Calls already resolved to a helper (a generic one's instance is found by probing its arguments). */
+    calleeCache = new Map();
     /** `file.ts:line` of the statement being lowered. */
     where;
     profile;
@@ -36,8 +41,15 @@ export class EmitterBase {
         this.model = analysis.model;
         // Each function resolves `typesol` names through its own file's imports.
         this.imports = target.imports;
-        this.scope = { imports: target.imports, enums: analysis.model.enums, options: analysis.model.options, dataEnums: analysis.model.dataEnums };
+        this.scope = {
+            imports: target.imports,
+            enums: analysis.model.enums,
+            options: analysis.model.options,
+            dataEnums: analysis.model.dataEnums,
+            typeArgs: "accounts" in target ? undefined : target.typeArgs,
+        };
         this.checker = analysis.checker;
+        this.analysis = analysis;
         if ("accounts" in target) {
             this.ix = target;
             for (const a of target.accounts) {
@@ -66,6 +78,54 @@ export class EmitterBase {
             }
         }
     }
+    /** The helper a call runs: a function, a const arrow function (top-level or local), or a generic one's instance. */
+    helperOf(node) {
+        if (!ts.isIdentifier(node.expression))
+            return undefined;
+        const cached = this.calleeCache.get(node);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const callee = node.expression;
+        const name = calleeName(callee, this.model.helperDecls, this.checker) ?? (this.lookup(callee.text) ? undefined : callee.text);
+        const g = name ? this.model.generics.get(name) : undefined;
+        let h = name ? this.model.helpers.get(name) : undefined;
+        if (g)
+            h = this.analysis.instantiate(g, this.typeArgsOf(node, g));
+        else if (h && node.typeArguments)
+            this.fail(node, `${h.display} takes no type arguments`);
+        this.calleeCache.set(node, h ?? null);
+        return h;
+    }
+    /** A generic call's type arguments: written out (`max<u64>(a, b)`), or the types of the arguments in `T` positions. */
+    typeArgsOf(node, g) {
+        const usage = `write ${g.display}<u64>(…) with the types`;
+        if (node.typeArguments) {
+            if (node.typeArguments.length !== g.typeParams.length)
+                this.fail(node, `${g.display} takes ${g.typeParams.length} type argument(s)`);
+            return node.typeArguments.map((t) => resolveScalarType(t, this.scope) ?? this.fail(t, "type arguments are integers, boolean, Pubkey or enums"));
+        }
+        return g.typeParams.map((tp) => {
+            for (const [i, p] of g.node.parameters.entries()) {
+                const arg = node.arguments[i];
+                if (!arg || !p.type || !ts.isTypeReferenceNode(p.type) || !ts.isIdentifier(p.type.typeName) || p.type.typeName.text !== tp || p.type.typeArguments)
+                    continue;
+                // Type the argument without emitting it: it is lowered again, once, by the call.
+                const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
+                const probe = this.reporter.guard(() => this.expr(arg));
+                this.lines.length = saved.lines;
+                this.hoisted.length = saved.hoisted;
+                this.temp = saved.temp;
+                this.reporter.diagnostics.length = saved.diagnostics;
+                if (!probe || probe.literal !== undefined || probe.isNull)
+                    continue;
+                if (!isScalar(probe.type))
+                    this.fail(arg, `${tp} stands for an integer, boolean, Pubkey or enum, not ${probe.type.kind}`);
+                const t = probe.type;
+                return t.kind === "pubkey" ? (t.hash ? { kind: "pubkey", hash: true } : { kind: "pubkey" }) : t;
+            }
+            return this.fail(node, `cannot tell what ${tp} is from literal arguments; ${usage}`);
+        });
+    }
     line(s) {
         // Runtime failures name the TypeScript line they come from: "TypeSOL: arithmetic overflow (vault.ts:42)".
         if (this.where)
@@ -136,7 +196,7 @@ export class EmitterBase {
         if ((ts.isPropertyAccessExpression(node) || ts.isCallExpression(node) || ts.isElementAccessExpression(node)) && node.questionDotToken)
             this.fail(node, "optional chaining (?.) is not supported; check `x !== null` first");
         if (ts.isNonNullExpression(node))
-            this.fail(node, "the ! assertion is not supported; check `x !== null` so TypeScript narrows it");
+            this.fail(node, "the ! assertion works on Option values only; check `x !== null` so TypeScript narrows it");
     }
     lookup(name) {
         for (let i = this.scopes.length - 1; i >= 0; i--) {

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

@@ -0,0 +1,13 @@
+import type { FieldType, ProgramModel, StructDef } from "../model.js";
+/**
+ * Accounts declared `@layout borsh` are stored as Anchor stores them (Borsh: a String or Vec takes 4 + its length, an
+ * empty Option one byte, and the fields after them move). An instruction unpacks such an account into the usual
+ * fixed-layout struct on the heap (`ts_unpack_<S>`, checking it as Borsh deserialization would), runs on that, and
+ * packs it back when it returns (`ts_pack_<S>`), so every language feature works on it unchanged.
+ */
+/** A field type whose Borsh bytes are its fixed-layout bytes: scalars, Pubkeys, unit enums, arrays and structs of them. */
+export declare function borshIdentical(t: FieldType, model: Pick<ProgramModel, "structs">): boolean;
+/** The fewest bytes a Borsh `S` can take (every String and Vec empty, every Option None). */
+export declare function borshMinSize(s: StructDef, model: Pick<ProgramModel, "structs">): number;
+/** C for `ts_unpack_<S>` and `ts_pack_<S>` of every `@layout borsh` struct. */
+export declare function emitBorshCodecs(model: ProgramModel): string[];

package/dist/compiler/emit/borsh.js

@@ -0,0 +1,232 @@
+/**
+ * Accounts declared `@layout borsh` are stored as Anchor stores them (Borsh: a String or Vec takes 4 + its length, an
+ * empty Option one byte, and the fields after them move). An instruction unpacks such an account into the usual
+ * fixed-layout struct on the heap (`ts_unpack_<S>`, checking it as Borsh deserialization would), runs on that, and
+ * packs it back when it returns (`ts_pack_<S>`), so every language feature works on it unchanged.
+ */
+/** A field type whose Borsh bytes are its fixed-layout bytes: scalars, Pubkeys, unit enums, arrays and structs of them. */
+export function borshIdentical(t, model) {
+    switch (t.kind) {
+        case "int":
+        case "bool":
+        case "pubkey":
+        case "enum":
+            return true;
+        case "array":
+            return borshIdentical(t.elem, model);
+        case "struct": {
+            const s = model.structs.get(t.name);
+            return !!s && s.layout !== "borsh" && s.fields.every((f) => borshIdentical(f.type, model));
+        }
+        default:
+            return false;
+    }
+}
+/** Bytes of a Borsh-identical type. */
+function fixedBytes(t, model) {
+    switch (t.kind) {
+        case "int":
+            return Number(t.name.slice(1)) / 8;
+        case "bool":
+        case "enum":
+            return 1;
+        case "pubkey":
+            return 32;
+        case "array":
+            return fixedBytes(t.elem, model) * t.len;
+        case "struct":
+            return model.structs.get(t.name).size;
+        default:
+            throw new Error(`unreachable: ${t.kind} has no fixed Borsh size`);
+    }
+}
+/** The fewest bytes a Borsh `S` can take (every String and Vec empty, every Option None). */
+export function borshMinSize(s, model) {
+    let n = 0;
+    for (const f of s.fields) {
+        const t = f.type;
+        if (t.kind === "fstring" || t.kind === "vec")
+            n += 4;
+        else if (t.kind === "option")
+            n += 1;
+        else
+            n += fixedBytes(t, model);
+    }
+    return n;
+}
+const DESER = `TS_FAIL(TS_ERR_ACCOUNT_TOO_SMALL, "TypeSOL: account data is not a valid Borsh value")`;
+const SER = `TS_FAIL(TS_ERR_DID_NOT_SERIALIZE, "TypeSOL: account data too small for the value")`;
+/** C for `ts_unpack_<S>` and `ts_pack_<S>` of every `@layout borsh` struct. */
+export function emitBorshCodecs(model) {
+    const out = [];
+    for (const s of model.structs.values()) {
+        if (s.layout !== "borsh" || s.size === undefined)
+            continue;
+        let k = 0;
+        const tmp = (p) => `${p}${k++}`;
+        // Bools and enum tags inside a Borsh-identical value: invalid ones fail, as Borsh deserialization does.
+        const validate = (t, lv, pad) => {
+            switch (t.kind) {
+                case "bool":
+                    return [`${pad}if (${lv} > 1) ${DESER};`];
+                case "enum":
+                    return [`${pad}if (${lv} >= ${model.enums.get(t.name).variants.length}) ${DESER};`];
+                case "array": {
+                    const i = tmp("i");
+                    const inner = validate(t.elem, `${lv}[${i}]`, `${pad}  `);
+                    return inner.length ? [`${pad}for (uint64_t ${i} = 0; ${i} < ${t.len}; ${i}++) {`, ...inner, `${pad}}`] : [];
+                }
+                case "struct":
+                    return model.structs.get(t.name).fields.flatMap((f) => validate(f.type, `${lv}.${f.name}`, pad));
+                default:
+                    return [];
+            }
+        };
+        // Bounds: the caller checked `len >= MIN` (the smallest Borsh form). Fixed-size pieces then always fit; only a
+        // String / Vec / Option payload is checked, against what is left after the fields that follow it still need.
+        const minOf = (t) => (t.kind === "fstring" || t.kind === "vec" ? 4 : t.kind === "option" ? 1 : fixedBytes(t, model));
+        const minAfter = s.fields.map((_, i) => s.fields.slice(i + 1).reduce((n, f) => n + minOf(f.type), 0));
+        const need = (n, rest, pad) => `${pad}if (${n} > len - at - ${rest}) ${DESER};`;
+        const room = (n, rest, pad) => `${pad}if (${n} > cap - at - ${rest}) ${SER};`;
+        // A String / Vec / Option field, `rest` bytes of later fields still to come.
+        const unpackVar = (t, lv, rest, pad) => {
+            switch (t.kind) {
+                case "fstring": {
+                    const l = tmp("n");
+                    // Strings were checked as UTF-8 when they came in (arguments) and are only stored whole: not checked again.
+                    return [
+                        `${pad}uint32_t ${l} = (uint32_t)ts_read_le(src + at, 4);`,
+                        `${pad}at += 4;`,
+                        `${pad}if (${l} > ${t.cap}) ${DESER};`,
+                        need(l, rest, pad),
+                        `${pad}${lv}.len = ${l};`,
+                        `${pad}ts_memcpy(${lv}.bytes, src + at, ${l});`,
+                        `${pad}at += ${l};`,
+                    ];
+                }
+                case "vec": {
+                    const l = tmp("n");
+                    const head = [
+                        `${pad}uint32_t ${l} = (uint32_t)ts_read_le(src + at, 4);`,
+                        `${pad}at += 4;`,
+                        `${pad}if (${l} > ${t.cap}) ${DESER};`,
+                        `${pad}${lv}.len = ${l};`,
+                    ];
+                    if (borshIdentical(t.elem, model)) {
+                        const n = fixedBytes(t.elem, model);
+                        const i = tmp("i");
+                        const check = validate(t.elem, `${lv}.items[${i}]`, `${pad}  `);
+                        return [
+                            ...head,
+                            need(`(uint64_t)${l} * ${n}`, rest, pad),
+                            `${pad}ts_memcpy(${lv}.items, src + at, (uint64_t)${l} * ${n});`,
+                            `${pad}at += (uint64_t)${l} * ${n};`,
+                            ...(check.length ? [`${pad}for (uint64_t ${i} = 0; ${i} < ${l}; ${i}++) {`, ...check, `${pad}}`] : []),
+                        ];
+                    }
+                    // Strings: each element's length prefix is checked as it is reached.
+                    const i = tmp("i");
+                    return [
+                        ...head,
+                        `${pad}for (uint64_t ${i} = 0; ${i} < ${l}; ${i}++) {`,
+                        need("4", rest, `${pad}  `),
+                        ...unpackVar(t.elem, `${lv}.items[${i}]`, rest, `${pad}  `),
+                        `${pad}}`,
+                    ];
+                }
+                case "option": {
+                    const tag = tmp("tag");
+                    const n = fixedBytes(t.inner, model);
+                    return [
+                        `${pad}uint8_t ${tag} = src[at++];`,
+                        `${pad}if (${tag} > 1) ${DESER};`,
+                        `${pad}${lv}.some = ${tag};`,
+                        `${pad}if (${tag}) {`,
+                        need(String(n), rest, `${pad}  `),
+                        `${pad}  ts_memcpy(&${lv}.v, src + at, ${n});`,
+                        `${pad}  at += ${n};`,
+                        ...validate(t.inner, `${lv}.v`, `${pad}  `),
+                        `${pad}}`,
+                    ];
+                }
+                default:
+                    throw new Error(`unreachable: ${t.kind} in a Borsh account`);
+            }
+        };
+        const packVar = (t, lv, rest, pad) => {
+            switch (t.kind) {
+                case "fstring": {
+                    const l = tmp("n");
+                    return [
+                        `${pad}uint32_t ${l} = ${lv}.len > ${t.cap} ? ${t.cap} : ${lv}.len;`,
+                        room(`4 + (uint64_t)${l}`, rest, pad),
+                        `${pad}ts_write_le(dst + at, ${l}, 4);`,
+                        `${pad}ts_memcpy(dst + at + 4, ${lv}.bytes, ${l});`,
+                        `${pad}at += 4 + (uint64_t)${l};`,
+                    ];
+                }
+                case "vec": {
+                    const l = tmp("n");
+                    if (borshIdentical(t.elem, model)) {
+                        const n = fixedBytes(t.elem, model);
+                        return [
+                            `${pad}uint32_t ${l} = ${lv}.len > ${t.cap} ? ${t.cap} : ${lv}.len;`,
+                            room(`4 + (uint64_t)${l} * ${n}`, rest, pad),
+                            `${pad}ts_write_le(dst + at, ${l}, 4);`,
+                            `${pad}ts_memcpy(dst + at + 4, ${lv}.items, (uint64_t)${l} * ${n});`,
+                            `${pad}at += 4 + (uint64_t)${l} * ${n};`,
+                        ];
+                    }
+                    const i = tmp("i");
+                    return [
+                        `${pad}uint32_t ${l} = ${lv}.len > ${t.cap} ? ${t.cap} : ${lv}.len;`,
+                        room("4", rest, pad),
+                        `${pad}ts_write_le(dst + at, ${l}, 4);`,
+                        `${pad}at += 4;`,
+                        `${pad}for (uint64_t ${i} = 0; ${i} < ${l}; ${i}++) {`,
+                        ...packVar(t.elem, `${lv}.items[${i}]`, rest, `${pad}  `),
+                        `${pad}}`,
+                    ];
+                }
+                case "option": {
+                    const n = fixedBytes(t.inner, model);
+                    return [
+                        room(`(uint64_t)(${lv}.some ? ${1 + n} : 1)`, rest, pad),
+                        `${pad}dst[at++] = ${lv}.some ? 1 : 0;`,
+                        `${pad}if (${lv}.some) {`,
+                        `${pad}  ts_memcpy(dst + at, &${lv}.v, ${n});`,
+                        `${pad}  at += ${n};`,
+                        `${pad}}`,
+                    ];
+                }
+                default:
+                    throw new Error(`unreachable: ${t.kind} in a Borsh account`);
+            }
+        };
+        // Runs of Borsh-identical fields are contiguous in both layouts: one copy each.
+        const unpackLines = [];
+        const packLines = [];
+        for (let i = 0; i < s.fields.length;) {
+            const f = s.fields[i];
+            if (borshIdentical(f.type, model)) {
+                let j = i;
+                let bytes = 0;
+                while (j < s.fields.length && borshIdentical(s.fields[j].type, model))
+                    bytes += fixedBytes(s.fields[j++].type, model);
+                unpackLines.push(`  ts_memcpy(&out->${f.name}, src + at, ${bytes});`, `  at += ${bytes};`);
+                for (const g of s.fields.slice(i, j))
+                    unpackLines.push(...validate(g.type, `out->${g.name}`, "  "));
+                // A pack can be short of room only after a String / Vec / Option grew; the start always fits (cap >= MIN).
+                packLines.push(...(i > 0 ? [room(String(bytes), minAfter[j - 1], "  ")] : []), `  ts_memcpy(dst + at, &in->${f.name}, ${bytes});`, `  at += ${bytes};`);
+                i = j;
+                continue;
+            }
+            unpackLines.push(...unpackVar(f.type, `out->${f.name}`, minAfter[i], "  "));
+            packLines.push(...packVar(f.type, `in->${f.name}`, minAfter[i], "  "));
+            i++;
+        }
+        const min = borshMinSize(s, model);
+        out.push(`/* ${s.name} as Borsh (Anchor's account layout) <-> its fixed-layout struct. */`, `__attribute__((noinline)) static uint64_t ts_unpack_${s.name}(const uint8_t *src, uint64_t len, TSS_${s.name} *out) {`, `  if (len < ${min}) ${DESER};`, `  uint64_t at = 0;`, ...unpackLines, `  return SUCCESS;`, `}`, `__attribute__((noinline)) static uint64_t ts_pack_${s.name}(const TSS_${s.name} *in, uint8_t *dst, uint64_t cap) {`, `  if (cap < ${min}) ${SER};`, `  uint64_t at = 0;`, ...packLines, `  return SUCCESS;`, `}`, "");
+    }
+    return out;
+}

package/dist/compiler/emit/calls.js

@@ -2,7 +2,7 @@ import ts from "typescript";
 import { resolveScalarType } from "../analyze.js";
 import { decodeAddress } from "../../keys.js";
 import { INT_INFO, INT_NAMES, isScalar, isWritable, sameType, scalarSize, typeName, } from "../model.js";
-import { U64, U8, I64, BOOL, PUBKEY, STRING, HASH, cBytes, cString, scalarC, scalarStorageC, optC, valueC, fieldC, storageDecl, accountMismatch, } from "./shared.js";
+import { U64, U8, I64, BOOL, PUBKEY, STRING, HASH, cBytes, cString, scalarC, scalarStorageC, optC, valueC, fieldC, storageDecl, accountMismatch, vecCount, } from "./shared.js";
 import { ExpressionEmitter } from "./expressions.js";
 /**
  * Calls: built-in functions, Vec methods, helpers, remaining accounts, foreign account reads and return data.
@@ -364,13 +364,14 @@ export class CallEmitter extends ExpressionEmitter {
                 this.line(`if (ts_find_pda(${seeds.name}, ${seeds.count}, ${program.c}, &${t}, &${b}) != SUCCESS) TS_FAIL(TS_ERR_SEEDS, "TypeSOL: no program address for these seeds");`);
                 return { c: `(&${t})`, type: PUBKEY };
             }
-            case "metadataAddress": {
+            case "metadataAddress":
+            case "masterEditionAddress": {
                 if (args.length !== 1)
-                    this.fail(node, "metadataAddress(mint) takes the mint");
+                    this.fail(node, `${builtin}(mint) takes the mint`);
                 const m = this.expect(this.expr(args[0], PUBKEY), PUBKEY, args[0]);
                 const t = this.tmp("md");
                 this.line(`SolPubkey ${t};`);
-                this.line(`TS_TRY(ts_metadata_address(${m.c}, &${t}));`);
+                this.line(`TS_TRY(${builtin === "metadataAddress" ? "ts_metadata_address" : "ts_master_edition_address"}(${m.c}, &${t}));`);
                 return { c: `(&${t})`, type: PUBKEY };
             }
             case "initExtraAccountMetas":
@@ -433,8 +434,9 @@ export class CallEmitter extends ExpressionEmitter {
         }
         if (builtin)
             this.fail(callee, `${builtin} cannot be called here`);
-        if (ts.isIdentifier(callee) && this.model.helpers.has(callee.text))
-            return this.callHelper(node, this.model.helpers.get(callee.text));
+        const helper = this.helperOf(node);
+        if (helper)
+            return this.callHelper(node, helper);
         if (ts.isPropertyAccessExpression(callee)) {
             const method = callee.name.text;
             // Vec<T> instruction arguments are read-only views.
@@ -520,10 +522,14 @@ export class CallEmitter extends ExpressionEmitter {
                     return this.ataOp(node, target, method);
                 if (target?.kind.kind === "metadataProgram")
                     return this.metadataOp(node, target, method);
-                if (target?.kind.kind === "coreProgram")
-                    return this.coreOp(node, target, method);
-                if (target?.kind.kind === "bubblegumProgram")
-                    return this.bubblegumOp(node, target, method);
+                // Each Metaplex CPI in its own C block: its data buffer's stack slot is reused by the next one.
+                if (target?.kind.kind === "coreProgram" || target?.kind.kind === "bubblegumProgram") {
+                    const t = target;
+                    this.line("{");
+                    this.block(() => (t.kind.kind === "coreProgram" ? this.coreOp(node, t, method) : this.bubblegumOp(node, t, method)));
+                    this.line("}");
+                    return undefined;
+                }
             }
         }
         if (ts.isPropertyAccessExpression(callee) && ts.isCallExpression(callee.expression) && this.exportName(callee.expression.expression) === "fixedArray")
@@ -536,7 +542,8 @@ export class CallEmitter extends ExpressionEmitter {
         const args = node.arguments;
         const vt = v.type;
         const info = v.vec;
-        const elemRef = (idx) => ({ ...v, lv: `${v.lv}[${idx}]`, type: vt.elem, vec: undefined, path: undefined });
+        const elemRef = (idx) => this.withFixedVec({ ...v, lv: `${info.items}[${idx}]`, type: vt.elem, vec: undefined, path: undefined });
+        const count = vecCount(info);
         /**
          * Evaluate the value into a temporary first (JS evaluates arguments before the call runs), then return a
          * writer for the element: `push(v.length)` sees the old length, `set(i, pop())` checks i after the pop.
@@ -564,6 +571,8 @@ export class CallEmitter extends ExpressionEmitter {
         // Elements removed or replaced here must not be referenced afterwards.
         const elemPaths = () => (ts.isPropertyAccessExpression(node.expression) ? this.pathsOf(node.expression.expression)?.map((p) => `${p}[]`) : undefined);
         const resize = (newLen, payer) => {
+            if (info.cap !== undefined)
+                return; // a FixedVec has its room already
             if (!info.resizable || !v.account)
                 this.fail(node, "only Vecs of declared Mut<...> / Init<...> accounts can grow or shrink");
             this.line(`TS_TRY(ts_resize(params, ${payer}, a_${v.account.name}, 8 + ${info.fixed} + (${newLen}) * ${info.elemSize}, entry_${v.account.name}));`);
@@ -577,11 +586,23 @@ export class CallEmitter extends ExpressionEmitter {
                     this.assertNotAliased(elemPaths(), node);
                 const i = this.indexValue(args[0]);
                 const write = stageElem(args[1]);
-                this.checkIndex(i, `(uint64_t)${info.len}`);
+                this.checkIndex(i, count);
                 write(elemRef(i));
                 return undefined;
             }
             case "push": {
+                if (info.cap !== undefined) {
+                    if (args.length !== 1)
+                        this.fail(node, "push(value) on a FixedVec takes the value (it has room for its capacity already)");
+                    needWritable();
+                    const write = stageElem(args[0]);
+                    const n = this.tmp("n");
+                    this.line(`uint64_t ${n} = ${count};`);
+                    this.line(`if (${n} >= ${info.cap}) TS_FAIL(TS_ERR_INDEX, "TypeSOL: push() on a full FixedVec");`);
+                    this.line(`${info.len} = (uint32_t)(${n} + 1);`);
+                    write(elemRef(n));
+                    return undefined;
+                }
                 if (args.length !== 2)
                     this.fail(node, "push(value, payer) takes the value and a Mut<Signer> that pays for the extra rent");
                 needWritable();
@@ -604,7 +625,7 @@ export class CallEmitter extends ExpressionEmitter {
                 this.assertNotAliased(elemPaths(), node);
                 const st = this.storageValueType(vt.elem);
                 const n = this.tmp("n");
-                this.line(`uint64_t ${n} = (uint64_t)${info.len};`);
+                this.line(`uint64_t ${n} = ${count};`);
                 this.line(`if (${n} == 0) TS_FAIL(TS_ERR_INDEX, "TypeSOL: pop() on an empty Vec");`);
                 // Structs and arrays are dropped (pop() as a statement); read .get(length - 1) first to keep one.
                 let result;
@@ -836,6 +857,8 @@ export class CallEmitter extends ExpressionEmitter {
         const s = targ && ts.isTypeReferenceNode(targ) && ts.isIdentifier(targ.typeName) ? this.model.structs.get(targ.typeName.text) : undefined;
         if (!s || s.size === undefined || s.vec)
             this.fail(node, "loadForeign needs a fixed-size struct type: loadForeign<Pool>(account, owner)");
+        if (s.layout === "borsh")
+            this.fail(node, `${s.name} is @layout borsh: loadForeign reads fixed layouts only`);
         if (node.arguments.length !== 2)
             this.fail(node, "loadForeign<T>(account, owner) takes the account and its owning program's address");
         const h = this.anyAccount(node.arguments[0], "loadForeign's account");
@@ -857,6 +880,8 @@ export class CallEmitter extends ExpressionEmitter {
         const s = targ && ts.isTypeReferenceNode(targ) && ts.isIdentifier(targ.typeName) ? this.model.structs.get(targ.typeName.text) : undefined;
         if (!s || s.size === undefined)
             this.fail(node, "loadAccount needs an account struct type: loadAccount<MyStruct>(account)");
+        if (s.layout === "borsh")
+            this.fail(node, `${s.name} is @layout borsh: declare it as an instruction parameter (remaining accounts are read in place)`);
         if (node.arguments.length !== 1)
             this.fail(node, "loadAccount<T>(account) takes one remaining account");
         const h = this.handle(node.arguments[0]);
@@ -876,7 +901,7 @@ export class CallEmitter extends ExpressionEmitter {
     }
     callHelper(node, h) {
         if (node.arguments.length !== h.params.length)
-            this.fail(node, `${h.name}() takes ${h.params.length} argument(s)`);
+            this.fail(node, `${h.display}() takes ${h.params.length} argument(s)`);
         // Arguments are evaluated left to right: settle earlier ones when a later one runs statements.
         // A helper that takes accounts may change account data, so account text it gets is copied first.
         const takesAccounts = h.params.some((p) => p.account);
@@ -898,13 +923,20 @@ export class CallEmitter extends ExpressionEmitter {
         // A helper that takes a writable struct account may replace anything stored in it (see assertNotAliased).
         for (const [i, p] of h.params.entries())
             if (p.account && p.account.kind === "account" && p.account.mut && ts.isIdentifier(node.arguments[i]))
-                this.assertNotAliased([node.arguments[i].text], node, h.name);
+                this.assertNotAliased([node.arguments[i].text], node, h.display);
         const args = ["params", ...pieces.map((x) => (typeof x === "number" ? (values[x].type.kind === "pubkey" ? `*(${values[x].c})` : values[x].c) : x))];
         if (!h.returns) {
             this.line(`TS_TRY(fn_${h.name}(${args.join(", ")}));`);
             return undefined;
         }
         const t = this.tmp();
+        if (h.returns.kind === "struct") {
+            // The result lives in a local the caller owns: a reference to it reads and copies like any struct. Declared at
+            // the top of the function, so a reference taken inside a block (a ternary's branch) stays valid after it.
+            this.hoisted.push(`  TSS_${h.returns.name} ${t};`);
+            this.line(`TS_TRY(fn_${h.name}(${[...args, `&${t}`].join(", ")}));`);
+            return { c: `(&${t})`, type: { kind: "structRef", struct: h.returns.name, writable: true } };
+        }
         this.line(`${scalarC(h.returns)} ${t};`);
         this.line(`TS_TRY(fn_${h.name}(${[...args, `&${t}`].join(", ")}));`);
         return h.returns.kind === "pubkey" ? { c: `(&${t})`, type: h.returns } : { c: t, type: h.returns };
@@ -916,6 +948,9 @@ export class CallEmitter extends ExpressionEmitter {
             const why = accountMismatch(acct.kind, p.account);
             if (why)
                 this.fail(n, `${h.name}() takes ${p.name} as ${why}`);
+            // A @layout borsh account goes with the struct it is being worked on as.
+            if (p.account.kind === "account" && p.account.struct.layout === "borsh")
+                return `a_${acct.name}, d_${acct.name}`;
             return `a_${acct.name}`;
         }
         switch (p.type.kind) {

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

@@ -2,6 +2,13 @@ import ts from "typescript";
 import { type AccountParam, type IdlSeed, type ValueType } from "../model.js";
 import { type Value } from "./shared.js";
 import { CallEmitter } from "./calls.js";
+/** One piece of a Metaplex instruction's Borsh data: fixed bytes, or a value lowered and serialized in source order. */
+type MplField = {
+    bytes: number[];
+} | {
+    value: ts.Expression;
+    type: ValueType;
+};
 /**
  * Other programs: PDAs and seeds, account creation, System/Token/ATA/Metaplex CPIs, generic invoke, Borsh
  * serialization and events.
@@ -30,10 +37,16 @@ export declare abstract class CpiEmitter extends CallEmitter {
     protected systemTransfer(node: ts.CallExpression): undefined;
     /** systemProgram.createAccount(payer, account, lamports, space, owner, signerSeeds?) */
     protected createAccount(node: ts.CallExpression, system: AccountParam): undefined;
-    /** Emit a CPI to the program account `program` with these metas (account, writable, signer). */
+    /**
+     * Emit a CPI to the program account `program` with these metas (account, writable, signer), and then (`tail`) a range
+     * of the remaining accounts, read-only (a Merkle proof).
+     */
     protected cpi(program: string, metas: [string, boolean, boolean][], buf: string, len: string, seeds: {
         name: string;
         count: number | string;
+    }, tail?: {
+        from: string;
+        to: string;
     }): void;
     protected signerSeeds(node: ts.Expression | undefined, authority: AccountParam, at: ts.Node): {
         name: string;
@@ -47,25 +60,35 @@ export declare abstract class CpiEmitter extends CallEmitter {
     protected tokenOp(node: ts.CallExpression, program: AccountParam, method: string): undefined;
     protected ataOp(node: ts.CallExpression, program: AccountParam, method: string): undefined;
     protected metadataOp(node: ts.CallExpression, program: AccountParam, method: string): undefined;
+    /** CreateMasterEditionV3 (17) and Verify (52) with VerificationArgs::CollectionV1. */
+    protected metadataCollectionOp(node: ts.CallExpression, program: AccountParam, method: string): undefined;
     /**
      * One account of a Metaplex CPI: an account parameter, or `null` for an optional account left out
      * (Metaplex programs take their own id in its place).
      */
     protected mplMeta(n: ts.Expression, program: AccountParam, what: string, writable: boolean, signer: boolean): [string, boolean, boolean];
     /** Borsh fields into a fresh buffer: raw bytes ("u8:N" style) or lowered values. */
-    protected mplData(at: ts.Node, max: number, fields: ({
-        bytes: number[];
-    } | {
-        value: ts.Expression;
-        type: ValueType;
-    })[]): {
+    protected mplData(at: ts.Node, max: number, fields: MplField[]): {
         buf: string;
         len: string;
     };
-    /** Metaplex Core: createAsset, createCollection, transferAsset, burnAsset (no plugins). */
+    /**
+     * Borsh of one Metaplex Core plugin literal (`{ kind: "FreezeDelegate", frozen: true, authority?: … }`): the Plugin
+     * enum, then (`withAuthority`) the Option<PluginAuthority> that CreateV1's PluginAuthorityPair and AddPluginV1 take.
+     */
+    protected corePlugin(n: ts.Expression, withAuthority: boolean): MplField[];
+    /** CreateV1 / CreateCollectionV1 plugins: Option<Vec<PluginAuthorityPair>>. */
+    protected corePluginList(n: ts.Expression | undefined): MplField[];
+    /** Metaplex Core: assets and collections (with plugins), plugins added, updated and removed, transfer and burn. */
     protected coreOp(node: ts.CallExpression, core: AccountParam, method: string): undefined;
+    /** PluginType (u8) from a kind string literal: removePlugin(…, "FreezeDelegate"). */
+    protected corePluginType(n: ts.Expression): MplField;
     /** Bubblegum (compressed NFTs on SPL account compression): createTree, mint (MintV1, no collection, no creators). */
     protected bubblegumOp(node: ts.CallExpression, bg: AccountParam, method: string): undefined;
+    /** Bubblegum V2 (trees on mpl-account-compression with mpl-noop; optional Metaplex Core collections). */
+    protected bubblegumV2(node: ts.CallExpression, bg: AccountParam, method: string): undefined;
+    /** `acct.key` of an account parameter, as an expression to serialize. */
+    protected keyOf(n: ts.Expression): ts.Expression;
     /**
      * `remainingAccounts()` (or a const bound to it): every remaining account; `rest.slice(a, b?)`: indexes a..b of them
      * (both checked against the count, 5104). C expressions for the range, relative to the first remaining account.
@@ -99,3 +122,4 @@ export declare abstract class CpiEmitter extends CallEmitter {
     /** Structs whose IDL description is the fixed layout: account data, arguments, and everything nested in them. */
     protected fixedLayoutStructs(): Set<string>;
 }
+export {};