@typesol/cli 0.16.0 → 0.18.0

package/dist/compiler/emit/storage.js

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { resolveScalarType } from "../analyze.js";
 import { INT_INFO, isScalar, isWritable, sameType, scalarSize, typeName } from "../model.js";
-import { U64, BOOL, PUBKEY, STRING, optC, fieldC, storageDecl } from "./shared.js";
+import { U64, BOOL, PUBKEY, STRING, optC, fieldC, fixedVecC, storageDecl, vecCount } from "./shared.js";
 import { EmitterBase } from "./base.js";
 /**
  * Places in account data and locals: references, reads and writes, Vec/array indexing, aliasing rules and
@@ -242,11 +242,14 @@ export class StorageEmitter extends EmitterBase {
     ref(node) {
         if (ts.isParenthesizedExpression(node))
             return this.ref(node.expression);
+        const unbanged = this.withoutBang(node);
+        if (unbanged)
+            return this.ref(unbanged);
         this.noOptionalChain(node);
         // A helper's struct result: a local of the caller's, read and copied like any struct.
         if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-            const h = this.model.helpers.get(node.expression.text);
-            if (h?.returns?.kind === "struct" && !this.lookup(node.expression.text)) {
+            const h = this.helperOf(node);
+            if (h?.returns?.kind === "struct") {
                 const v = this.callHelper(node, h);
                 return { lv: `(*${v.c})`, type: { kind: "struct", name: h.returns.name }, writable: true };
             }
@@ -273,13 +276,16 @@ export class StorageEmitter extends EmitterBase {
                         return undefined;
                     this.assertUsable(a, node);
                     const r = { lv: `d_${a.name}->${f.name}`, type: f.type, writable: isWritable(a.kind), account: a, path: [f.name] };
-                    if (f.type.kind === "vec")
-                        // Growing needs the account's length at instruction entry: only instructions know it.
+                    if (f.type.kind === "vec" && f.type.cap !== undefined)
+                        r.vec = this.fixedVec(r.lv, f.type.elem, f.type.cap);
+                    else if (f.type.kind === "vec")
+                        // Growing needs the account's length at instruction entry: instructions have it, helpers get it passed.
                         r.vec = {
                             len: `d_${a.name}->${f.name}__len`,
+                            items: r.lv,
                             fixed: `sizeof(TSS_${a.kind.struct.name})`,
                             elemSize: a.kind.struct.vec.elemSize,
-                            resizable: isWritable(a.kind) && !!this.ix,
+                            resizable: isWritable(a.kind),
                         };
                     return r;
                 }
@@ -307,7 +313,7 @@ export class StorageEmitter extends EmitterBase {
                 // TypeScript proved the variant set; this runtime check is the backstop.
                 const cond = located.map((l) => `${base.lv}.tag != ${l.vi}`).join(" && ");
                 this.line(`if (${cond}) TS_FAIL(TS_ERR_ENUM_VARIANT, "TypeSOL: ${e.name} is not ${names.join("/")}");`);
-                return { ...base, lv: `${base.lv}.v.${first.name}.${first.f.name}`, type: first.f.type, path: undefined, vec: undefined };
+                return this.withFixedVec({ ...base, lv: `${base.lv}.v.${first.name}.${first.f.name}`, type: first.f.type, path: undefined, vec: undefined });
             }
             if (base && base.type.kind === "option" && base.type.inner.kind === "struct") {
                 const s = this.model.structs.get(base.type.inner.name);
@@ -315,7 +321,7 @@ export class StorageEmitter extends EmitterBase {
                 if (!f)
                     this.fail(node.name, `${s.name} has no field "${field}"`);
                 this.line(`if (!${base.lv}.some) TS_FAIL(TS_ERR_UNWRAP, "TypeSOL: option is empty");`);
-                return { ...base, lv: `${base.lv}.v.${f.name}`, type: f.type, path: undefined, vec: undefined };
+                return this.withFixedVec({ ...base, lv: `${base.lv}.v.${f.name}`, type: f.type, path: undefined, vec: undefined });
             }
             if (base && base.type.kind === "struct") {
                 const s = this.model.structs.get(base.type.name);
@@ -324,9 +330,9 @@ export class StorageEmitter extends EmitterBase {
                     this.fail(node.name, `${s.name} has no field "${field}"`);
                 const r = { ...base, lv: `${base.lv}.${f.name}`, type: f.type, path: base.path && [...base.path, f.name], vec: undefined };
                 // Vecs of loaded accounts can be read and updated in place but not resized (no entry length known).
-                if (f.type.kind === "vec")
-                    r.vec = { len: `${base.lv}.${f.name}__len`, fixed: `sizeof(TSS_${s.name})`, elemSize: s.vec.elemSize, resizable: false };
-                return r;
+                if (f.type.kind === "vec" && f.type.cap === undefined)
+                    r.vec = { len: `${base.lv}.${f.name}__len`, items: r.lv, fixed: `sizeof(TSS_${s.name})`, elemSize: s.vec.elemSize, resizable: false };
+                return this.withFixedVec(r);
             }
             return undefined;
         }
@@ -334,7 +340,7 @@ export class StorageEmitter extends EmitterBase {
         if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "get") {
             const owner = node.expression.expression;
             const l = ts.isIdentifier(owner) ? this.lookup(owner.text) : undefined;
-            if (l?.type.kind === "vecArg" && !isScalar(l.type.elem)) {
+            if (l?.type.kind === "vecArg" && !isScalar(l.type.elem) && l.type.elem.kind !== "string") {
                 // A Vec<Struct> argument: elements are read in place (validated when the instruction started).
                 if (node.arguments.length !== 1)
                     this.fail(node, "get(index) takes one argument");
@@ -345,8 +351,9 @@ export class StorageEmitter extends EmitterBase {
             if (base && (base.type.kind === "array" || base.type.kind === "vec")) {
                 if (node.arguments.length !== 1)
                     this.fail(node, "get(index) takes one argument");
-                const idx = this.index(node.arguments[0], base.type.kind === "array" ? `${base.type.len}ULL` : `(uint64_t)${base.vec.len}`);
-                return { ...base, lv: `${base.lv}[${idx}]`, type: base.type.elem, path: undefined, vec: undefined };
+                const idx = this.index(node.arguments[0], base.type.kind === "array" ? `${base.type.len}ULL` : vecCount(base.vec));
+                const lv = base.type.kind === "array" ? `${base.lv}[${idx}]` : `${base.vec.items}[${idx}]`;
+                return this.withFixedVec({ ...base, lv, type: base.type.elem, path: undefined, vec: undefined });
             }
         }
         return undefined;
@@ -474,7 +481,19 @@ export class StorageEmitter extends EmitterBase {
      * Write a struct or array into storage: from an object literal (field by field, every field
      * required) or by copying another location of the same type.
      */
+    /** A whole struct account copied as a value (`return vault`, `info = vault`): fixed-size structs only. */
+    wholeAccount(node) {
+        if (!ts.isIdentifier(node) || this.lookup(node.text))
+            return undefined;
+        const a = this.accounts.get(node.text);
+        if (!a || !(a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "initIfNeeded") || a.kind.struct.size === undefined || a.kind.struct.vec)
+            return undefined;
+        this.assertUsable(a, node);
+        return { lv: `(*d_${a.name})`, type: { kind: "struct", name: a.kind.struct.name }, writable: false };
+    }
     writeAggregate(target, valueNode) {
+        if (ts.isParenthesizedExpression(valueNode))
+            return this.writeAggregate(target, valueNode.expression);
         if (target.type.kind === "option" && target.type.inner.kind === "struct") {
             if (valueNode.kind === ts.SyntaxKind.NullKeyword) {
                 this.line(`${target.lv}.some = 0;`);
@@ -534,6 +553,35 @@ export class StorageEmitter extends EmitterBase {
             this.line(`ts_memcpy(&${target.lv}, &${tmp}, sizeof(${tmp}));`);
             return;
         }
+        if (target.type.kind === "vec" && target.type.cap !== undefined && ts.isCallExpression(valueNode) && this.exportName(valueNode.expression) === "fixedVec") {
+            const list = valueNode.arguments[0];
+            if (valueNode.arguments.length !== 1 || !ts.isArrayLiteralExpression(list))
+                this.fail(valueNode, "fixedVec([…]) takes an array literal");
+            return this.writeAggregate(target, list);
+        }
+        if (target.type.kind === "vec" && target.type.cap !== undefined && ts.isArrayLiteralExpression(valueNode)) {
+            // `list = [a, b]`: built in a temporary (the elements may read the old list), the unused slots zeroed.
+            const t = target.type;
+            const els = valueNode.elements;
+            if (els.length > t.cap)
+                this.fail(valueNode, `${els.length} elements do not fit in ${typeName(t)}`);
+            const tmp = this.tmp("fv");
+            this.line(`${fixedVecC(t)} ${tmp};`);
+            this.line(`ts_memzero(&${tmp}, sizeof(${tmp}));`);
+            this.line(`${tmp}.len = ${els.length};`);
+            els.forEach((e, i) => {
+                if (ts.isSpreadElement(e))
+                    this.fail(e, "list the elements one by one");
+                const sub = { lv: `${tmp}.items[${i}]`, type: t.elem, writable: true };
+                const vt = this.storageValueType(t.elem);
+                if (vt)
+                    this.line(this.writeStorage(sub, this.ownedString(this.expect(this.expr(e, vt), vt, e)).c) + ";");
+                else
+                    this.writeAggregate(sub, e);
+            });
+            this.line(`ts_memcpy(&${target.lv}, &${tmp}, sizeof(${tmp}));`);
+            return;
+        }
         if (ts.isObjectLiteralExpression(valueNode)) {
             if (target.type.kind !== "struct")
                 this.fail(valueNode, `expected a ${typeName(target.type)}, not an object literal`);
@@ -569,12 +617,33 @@ export class StorageEmitter extends EmitterBase {
             this.line(`ts_memcpy(&${target.lv}, &${tmp}, sizeof(${tmp}));`);
             return;
         }
-        const src = this.ref(valueNode);
+        if (ts.isConditionalExpression(valueNode)) {
+            // `cond ? a : b` (places, literals or calls): each branch writes the target. A branch that reads the target
+            // copies it onto itself, which the copies below allow.
+            const cond = this.expect(this.expr(valueNode.condition, BOOL), BOOL, valueNode.condition);
+            this.line(`if (${cond.c}) {`);
+            this.block(() => this.writeAggregate(target, valueNode.whenTrue));
+            this.line(`} else {`);
+            this.block(() => this.writeAggregate(target, valueNode.whenFalse));
+            this.line(`}`);
+            return;
+        }
+        const src = this.ref(valueNode) ?? this.wholeAccount(valueNode);
         if (!src || !sameType(src.type, target.type))
             this.fail(valueNode, `expected a ${typeName(target.type)}: an object literal or another ${typeName(target.type)}`);
         // Same-typed places are either distinct or identical (`a.p = a.p`); ts_copy skips the latter.
         this.line(`ts_copy(&${target.lv}, &${src.lv}, sizeof(${target.lv}));`);
     }
+    /** The Vec view of a FixedVec stored at `lv` (`{ len, items[cap] }`). */
+    fixedVec(lv, elem, cap) {
+        return { len: `${lv}.len`, items: `${lv}.items`, fixed: "", elemSize: this.fieldBytes(elem), resizable: false, cap };
+    }
+    /** A place whose type is a FixedVec gets its Vec view. */
+    withFixedVec(r) {
+        if (r.type.kind === "vec" && r.type.cap !== undefined)
+            r.vec = this.fixedVec(r.lv, r.type.elem, r.type.cap);
+        return r;
+    }
     /** `arr.get(i)` reads storage rather than calling anything. */
     isStorageCall(node) {
         return ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "get" && !!this.peekArray(node.expression.expression);
@@ -658,8 +727,11 @@ export class StorageEmitter extends EmitterBase {
                 return this.fieldBytes(t.elem) * t.len;
             case "struct":
                 return this.model.structs.get(t.name).size;
-            case "string":
             case "vec":
+                if (t.cap !== undefined)
+                    return 4 + this.fieldBytes(t.elem) * t.cap;
+                throw new Error("unreachable: variable-size field has no fixed size");
+            case "string":
                 throw new Error("unreachable: variable-size field has no fixed size");
         }
     }

package/dist/compiler/idl.js

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { snakeCase } from "./analyze.js";
 import { decodeAddress } from "../keys.js";
-import { isWritable, optionKey } from "./model.js";
+import { fixedVecName, isWritable, optionKey, typeName, } from "./model.js";
 const SYSTEM_PROGRAM = "11111111111111111111111111111111";
 const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
 const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
@@ -37,6 +37,19 @@ const fixedEnumName = (name) => `FixedEnum_${name}`;
  * IDL type of a field or value. `borshOption` picks the encoding of Option: Borsh `option` for
  * instruction arguments and events, the fixed { is_some, value } struct for account data.
  */
+/** IDL type of a @layout borsh account's field: Anchor's own (`string`, `{ vec }`, `{ option }`). */
+function borshIdlType(t) {
+    if (t.kind === "fstring")
+        return "string";
+    if (t.kind === "vec")
+        return { vec: borshIdlType(t.elem) };
+    if (t.kind === "option")
+        return { option: idlType(t.inner) };
+    // A data enum in a Borsh struct is the Borsh enum itself (tag, then the variant's fields).
+    if (t.kind === "dataEnum")
+        return { defined: { name: t.name } };
+    return idlType(t);
+}
 function idlType(t, borshOption = false) {
     switch (t.kind) {
         case "int":
@@ -62,7 +75,7 @@ function idlType(t, borshOption = false) {
             // Borsh enum in arguments and events; fixed tag + payload in account data.
             return borshOption || t.kind === "dataEnumArg" ? { defined: { name: t.name } } : { defined: { name: fixedEnumName(t.name) } };
         case "vec":
-            return { vec: idlType(t.elem) };
+            return t.cap === undefined ? { vec: idlType(t.elem) } : { defined: { name: fixedVecName(t) } };
         case "vecArg":
             return { vec: idlType(t.elem) };
         case "arrayArg":
@@ -80,7 +93,7 @@ function accountEntry(ix, name, k, programAddress) {
         entry.writable = true;
     if (param?.optional)
         entry.optional = true;
-    if (k.kind === "signer")
+    if (k.kind === "signer" || param?.signsInit)
         entry.signer = true;
     if (k.kind === "system")
         entry.address = SYSTEM_PROGRAM;
@@ -125,7 +138,7 @@ function accountEntry(ix, name, k, programAddress) {
 export function buildIdl(model, address, version = "0.1.0") {
     const structs = [...model.structs.values()];
     const usedStructs = structs.filter((s) => model.accountStructs.has(s.name) || model.events.has(s.name) || s.size !== undefined);
-    return {
+    const idl = {
         address,
         metadata: { name: model.name, version, spec: "0.1.0", description: "Built with TypeSOL" },
         instructions: model.instructions.map((ix) => ({
@@ -148,7 +161,7 @@ export function buildIdl(model, address, version = "0.1.0") {
                     fields: s.fields.map((f) => ({
                         name: snakeCase(f.name),
                         ...docsOf(s.node.members.find((m) => m.name && ts.isIdentifier(m.name) && m.name.text === f.name)),
-                        type: idlType(f.type, model.events.has(s.name) && !model.accountStructs.has(s.name)),
+                        type: s.layout === "borsh" ? borshIdlType(f.type) : idlType(f.type, model.events.has(s.name) && !model.accountStructs.has(s.name)),
                     })),
                 },
             })),
@@ -201,6 +214,17 @@ export function buildIdl(model, address, version = "0.1.0") {
                     ],
                 },
             })),
+            ...[...model.fixedVecs].map(([name, t]) => ({
+                name,
+                docs: [`TypeSOL FixedVec<${typeName(t.elem)}, ${t.cap}>: \`len\` elements in use, room for ${t.cap} (the rest zero or stale).`],
+                type: {
+                    kind: "struct",
+                    fields: [
+                        { name: "len", type: "u32" },
+                        { name: "items", type: { array: [idlType(t.elem), t.cap] } },
+                    ],
+                },
+            })),
             ...[...model.fstrings]
                 .sort((a, b) => a - b)
                 .map((cap) => ({
@@ -216,4 +240,12 @@ export function buildIdl(model, address, version = "0.1.0") {
             })),
         ],
     };
+    // FixedString / FixedVec / FixedOption types only @layout borsh accounts declared (they list theirs as string / vec /
+    // option) are left out.
+    // FixedVecs first: a kept one may name a FixedString.
+    for (const prefix of [/^FixedVec\d/, /^FixedOption_/, /^FixedString\d/]) {
+        const text = JSON.stringify([idl.instructions, idl.types.filter((t) => !prefix.test(t.name))]);
+        idl.types = idl.types.filter((t) => !prefix.test(t.name) || text.includes(`"name":"${t.name}"`));
+    }
+    return idl;
 }

package/dist/compiler/model.d.ts

@@ -110,9 +110,11 @@ export type FieldType = ScalarType | {
     name: string;
 }
 /** `Vec<T>`: Borsh u32 length + elements. Only as the last field of an account struct. */
+/** `Vec<T>` (last field, grows the account) or, with `cap`, `FixedVec<T, N>`: a u32 length and room for N elements. */
  | {
     kind: "vec";
     elem: FieldType;
+    cap?: number;
 };
 export interface StructField {
     name: string;
@@ -136,14 +138,27 @@ export interface StructDef {
     accountDiscriminator: number[];
     eventDiscriminator: number[];
     node: ts.InterfaceDeclaration;
+    /**
+     * How account data stores it: "fixed" (every field at a fixed offset, the default) or "borsh" (`@layout borsh`:
+     * Anchor's bytes, where strings, Vecs and Options take only what they hold).
+     */
+    layout: "fixed" | "borsh";
+    /**
+     * A @layout borsh struct with a `string` field or a data enum carrying strings: they are views of the bytes it was
+     * read from, so it is an argument, return value or event, never account data.
+     */
+    viewsOnly?: boolean;
 }
 export type TokenProgramKind = "token" | "token2022" | "tokenInterface";
 export type ParamKind = {
     kind: "signer";
     mut: boolean;
-} | {
+}
+/** `systemOwned`: a SystemAccount (Anchor's): owned by the System Program (3011). */
+ | {
     kind: "info";
     mut: boolean;
+    systemOwned?: boolean;
 } | {
     kind: "account";
     struct: StructDef;
@@ -168,9 +183,12 @@ export type ParamKind = {
     kind: "token";
     mut: boolean;
     init?: "create" | "ifNeeded";
-} | {
+}
+/** `init`: created in the body (`mint.create(payer, seeds | null, decimals, authority, freeze)`). */
+ | {
     kind: "mint";
     mut: boolean;
+    init?: "create" | "ifNeeded";
 } | {
     kind: "system";
 } | {
@@ -253,6 +271,8 @@ export interface AccountParam {
     optional?: boolean;
     node: ts.ParameterDeclaration;
     constraints: Constraints;
+    /** Created in the body as a new keypair account (`create(payer, null, …)`), so it signs: the IDL says so. */
+    signsInit?: boolean;
 }
 export interface ArgParam {
     name: string;
@@ -280,6 +300,8 @@ export interface Instruction {
     minArgsSize: number;
     /** Sent as return data: a scalar in Borsh, or a fixed-size struct in its fixed layout (as the IDL describes it). */
     returns: ScalarType | {
+        kind: "string";
+    } | {
         kind: "struct";
         name: string;
     } | undefined;
@@ -291,6 +313,16 @@ export interface Instruction {
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
 }
+/** A helper with type parameters, before it is instantiated. */
+export interface GenericHelper {
+    name: string;
+    display: string;
+    /** Indexes of parameters with a function type (`f: (x: u64) => u64`): bound per call to a named function. */
+    fnParams: number[];
+    node: HelperNode;
+    typeParams: string[];
+    imports: Map<string, string>;
+}
 export interface HelperParam {
     name: string;
     /** `{ kind: "account" }` for account parameters (then `account` says which kind). */
@@ -298,16 +330,36 @@ export interface HelperParam {
     account?: ParamKind;
     node: ts.ParameterDeclaration;
 }
-/** A non-exported function (or any function of an imported file): values and accounts in; void, a scalar or a struct out. */
+/** A function written as `function f(…)`, `const f = (…) => …` or `const f = function (…) {…}`. */
+export type HelperNode = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/**
+ * A non-exported function (or any function of an imported file), or an arrow function declared with const at the top
+ * level or inside a function (capturing nothing): values and accounts in; void, a scalar or a struct out.
+ */
 export interface Helper {
+    /** The C name (fn_<name>): the function's name, `outer__local` for a local arrow, `name__u64` for an instance. */
     name: string;
+    /** The name in messages: `local`, `max<u64>`. */
+    display: string;
     params: HelperParam[];
     /** A struct result is written through an out pointer (`TSS_<name> *ret`) that the caller provides. */
     returns: ScalarType | {
+        kind: "string";
+    } | {
         kind: "struct";
         name: string;
     } | undefined;
-    node: ts.FunctionDeclaration;
+    node: HelperNode;
+    /** The body; an arrow's expression body is one return (or expression) statement. */
+    statements: readonly ts.Statement[];
+    /** A generic helper's instance: type parameter -> the type it stands for. */
+    typeArgs?: Map<string, ScalarType>;
+    /** A generic helper's instance: type parameter -> the struct it stands for. */
+    structArgs?: Map<string, string>;
+    /** An instance's function parameters: name -> the helper passed for it (its calls go there). */
+    fnArgs?: Map<string, string>;
+    /** Their argument positions, which have no C parameter. */
+    fnArgIndexes?: number[];
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
 }
@@ -352,6 +404,12 @@ export interface ProgramModel {
     structs: Map<string, StructDef>;
     instructions: Instruction[];
     helpers: Map<string, Helper>;
+    /** Generic helpers by name: instantiated (into `helpers`) for the types each call uses. */
+    generics: Map<string, GenericHelper>;
+    /** Declaration (function, or the const of an arrow) -> helper or generic name, for calls to local arrows. */
+    helperDecls: Map<ts.Node, string>;
+    /** Local closures (they read the enclosing function's variables): their declaration -> name; expanded where called. */
+    closureDecls: Map<ts.Node, string>;
     errors: ErrorDef[];
     /** Enum name -> member name -> error */
     errorEnums: Map<string, Map<string, ErrorDef>>;
@@ -374,6 +432,10 @@ export interface ProgramModel {
     argStructs: Set<string>;
     /** FixedString capacities in use, for C typedefs and IDL types. */
     fstrings: Set<number>;
+    /** FixedVec<T, N> types in use (IDL name -> type), for IDL types. */
+    fixedVecs: Map<string, FieldType & {
+        kind: "vec";
+    }>;
 }
 export declare function isWritable(k: ParamKind): boolean;
 export declare function typeName(t: ValueType | FieldType): string;
@@ -386,3 +448,7 @@ export declare function optionKey(t: ScalarType | {
     name: string;
 }): string;
 export declare function scalarKey(t: ScalarType): string;
+/** The IDL type name of a FixedVec<T, N>: `FixedVec<N>_<T>`. */
+export declare function fixedVecName(t: FieldType & {
+    kind: "vec";
+}): string;

package/dist/compiler/model.js

@@ -56,7 +56,7 @@ export function typeName(t) {
         case "enumRef":
             return t.name;
         case "vec":
-            return `Vec<${typeName(t.elem)}>`;
+            return t.cap === undefined ? `Vec<${typeName(t.elem)}>` : `FixedVec<${typeName(t.elem)}, ${t.cap}>`;
         case "vecArg":
             return `Vec<${typeName(t.elem)}>`;
         case "arrayArg":
@@ -92,7 +92,7 @@ export function sameType(a, b) {
         case "option":
             return sameType(a.inner, b.inner);
         case "vec":
-            return sameType(a.elem, b.elem);
+            return a.cap === b.cap && sameType(a.elem, b.elem);
         case "vecArg":
             return sameType(a.elem, b.elem);
         case "arrayArg":
@@ -120,3 +120,9 @@ export function optionKey(t) {
 export function scalarKey(t) {
     return t.kind === "int" ? t.name : t.kind === "enum" ? `e_${t.name}` : t.kind === "pubkey" && t.hash ? "hash" : t.kind;
 }
+/** The IDL type name of a FixedVec<T, N>: `FixedVec<N>_<T>`. */
+export function fixedVecName(t) {
+    return `FixedVec${t.cap}_${typeName(t.elem)
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/_+$/, "")}`;
+}

package/dist/portgen.js

@@ -4,8 +4,9 @@
  * It writes the account structs, enums, errors, events and one function per instruction with its accounts and
  * arguments, bodies left to fill in. Instructions keep their discriminators (an explicit `@discriminator` when the
  * name would derive another), account structs keep their names (so their discriminators), errors keep their order —
- * so existing clients keep working when the layout allows it. Where TypeSOL stores data differently from Anchor's Borsh
- * layout (String, Option and a Vec that is not the last field in account data), it says so in a note and a comment.
+ * so existing clients keep working. Account structs holding a String, Vec or Option get `@layout borsh`, so they keep
+ * Anchor's bytes (existing accounts stay readable); where a layout still differs (a String or Vec nested in a struct, a
+ * data enum, a COption) it says so in a note and a comment.
  */
 import { createHash } from "node:crypto";
 import { cNameProblem } from "./compiler/analyze.js";
@@ -83,6 +84,34 @@ export function generatePort(idl) {
     for (const ix of idl.instructions)
         for (const g of ix.args)
             mark(g.type, "arg");
+    // Structs passed or returned whole (not inside another type): these can keep Anchor's Borsh bytes with @layout borsh.
+    const whole = new Set();
+    const nested = new Set();
+    const inside = (t) => {
+        if (!t || typeof t === "string")
+            return;
+        const inner = t.vec ?? t.option ?? t.coption ?? t.array?.[0];
+        if (inner)
+            return inside(inner);
+        if (t.defined)
+            nested.add(definedName(t.defined));
+    };
+    for (const ix of idl.instructions) {
+        for (const t of [...ix.args.map((g) => g.type), ix.returns]) {
+            if (t && typeof t === "object" && t.defined)
+                whole.add(definedName(t.defined));
+            else if (t && typeof t === "object")
+                inside(t.vec ?? t.option ?? t.coption ?? t.array?.[0]);
+        }
+    }
+    for (const def of idl.types ?? []) {
+        for (const f of (def.type.fields ?? []))
+            if (typeof f === "object" && f && "type" in f)
+                inside(f.type);
+        for (const v of def.type.variants ?? [])
+            for (const f of v.fields ?? [])
+                inside(typeof f === "object" && f && "type" in f ? f.type : f);
+    }
     const fixed = (w) => w === "account" || w === "struct" || w === "variant";
     const describe = (w) => (w === "account" ? "account data" : w === "struct" ? "a struct argument" : "a data-enum variant");
     const tsType = (t, where, at, last = false) => {
@@ -152,6 +181,57 @@ export function generatePort(idl) {
         notes.push(`${at}: unsupported IDL type ${JSON.stringify(t)}; left as u64`);
         return `${use("u64")} /* TODO */`;
     };
+    /** A String, Vec or Option at a struct's top level: Borsh-sized in Anchor. */
+    const borshOnly = (t) => t === "string" || t === "bytes" || (typeof t === "object" && (!!t.vec || !!t.option));
+    /** A field's type in a `@layout borsh` struct, or undefined when that layout cannot hold it. Notes the capacities. */
+    const borshField = (t, at) => {
+        const quiet = at === "";
+        const fixedOk = (u) => {
+            if (typeof u === "string")
+                return INTS.has(u) || u === "bool" || u === "pubkey" || u === "publicKey";
+            if (u.array)
+                return Number.isInteger(Number(u.array[1])) && fixedOk(u.array[0]);
+            if (u.defined) {
+                const name = definedName(u.defined);
+                const d = defs.get(name);
+                if (!d || skipped.has(name) || helperDefs.has(name))
+                    return false;
+                if (d.type.kind === "enum")
+                    return (d.type.variants ?? []).every((v) => !v.fields?.length);
+                return (d.type.fields ?? []).every((f) => fixedOk(f.type));
+            }
+            return false;
+        };
+        if (t === "string") {
+            if (!quiet)
+                notes.push(`${at}: set the String's capacity to Anchor's #[max_len] (Borsh bytes are kept: @layout borsh)`);
+            return `${use("FixedString")}<32> /* TODO: #[max_len] */`;
+        }
+        if (t === "bytes")
+            return borshField({ vec: "u8" }, at);
+        if (typeof t === "object" && t.vec) {
+            const elem = t.vec === "string"
+                ? `${use("FixedString")}<32> /* TODO: #[max_len] */`
+                : fixedOk(t.vec) && !quiet
+                    ? tsType(t.vec, "account", at)
+                    : fixedOk(t.vec)
+                        ? "x"
+                        : undefined;
+            if (elem === undefined)
+                return undefined;
+            if (!quiet)
+                notes.push(`${at}: set the Vec's capacity to Anchor's #[max_len] (Borsh bytes are kept: @layout borsh)`);
+            return `${use("FixedVec")}<${elem}, 8> /* TODO: #[max_len] */`;
+        }
+        if (typeof t === "object" && t.option) {
+            if (!fixedOk(t.option))
+                return undefined;
+            return quiet ? "x" : `${use("Option")}<${tsType(t.option, "account", at)}>`;
+        }
+        if (!fixedOk(t))
+            return undefined;
+        return quiet ? "x" : tsType(t, "account", at);
+    };
     const esc = (s) => s.replace(/\*\//g, "* /");
     const docs = (lines, pad = "") => (lines?.length ? `${pad}/** ${esc(lines.join(" "))} */\n` : "");
     const out = [];
@@ -180,8 +260,13 @@ export function generatePort(idl) {
         const where = used.has("account") ? "account" : used.has("arg") ? "struct" : used.has("event") ? "event" : "account";
         if (def.type.kind === "struct") {
             const fields = (def.type.fields ?? []);
+            // An account struct, or one passed / returned whole, with a String, Vec or Option of its own: `@layout borsh`
+            // keeps Anchor's bytes.
+            const borshable = accountNames.has(def.name) || (whole.has(def.name) && !nested.has(def.name) && !eventNames.has(def.name));
+            const borsh = borshable && !isTuple(fields) && fields.some((f) => borshOnly(f.type)) && fields.every((f) => borshField(f.type, "") !== undefined);
             const tag = accountNames.has(def.name) ? " (account)" : eventNames.has(def.name) ? ` (event: emit<${typeName(def.name)}>({ … }))` : "";
-            out.push(docs(def.docs).trimEnd() || `/** ${def.name}${tag} */`);
+            const doc = def.docs?.length ? esc(def.docs.join(" ")) : `${def.name}${tag}`;
+            out.push(borsh ? `/**\n * ${doc}\n * @layout borsh\n */` : `/** ${doc} */`);
             out.push(`export interface ${typeName(def.name)} {`);
             const seen = new Set();
             fields.forEach((f, i) => {
@@ -189,7 +274,8 @@ export function generatePort(idl) {
                 while (seen.has(n))
                     n = `${n}2`;
                 seen.add(n);
-                out.push(`${docs(f.docs, "  ")}  ${n}: ${tsType(f.type, where, `${def.name}.${f.name}`, i === fields.length - 1)};`);
+                const ty = borsh ? borshField(f.type, `${def.name}.${f.name}`) : tsType(f.type, where, `${def.name}.${f.name}`, i === fields.length - 1);
+                out.push(`${docs(f.docs, "  ")}  ${n}: ${ty};`);
             });
             out.push("}", "");
         }

package/docs/errors.md

@@ -11,22 +11,24 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 2009 | not the associated token account (ConstraintAssociated) |
 | 2012 | not the expected address (ConstraintAddress) |
 | 2014 / 2015 | token account mint / owner mismatch (ConstraintTokenMint / ConstraintTokenOwner) |
-| 2016 / 2017 | mint authority / freeze authority mismatch |
+| 2016 / 2017 / 2018 | mint authority / freeze authority / decimals mismatch (2018: an existing mint `createIfNeeded` found) |
 | 2040 | the same account passed in two writable slots (ConstraintDuplicateMutableAccount) |
 | 3000 | account already exists / initialized (AccountDiscriminatorAlreadySet) |
 | 3002 | discriminator mismatch (AccountDiscriminatorMismatch) |
-| 3003 | data too small, not an initialized token account / mint, or a read past the end (AccountDidNotDeserialize) |
+| 3003 | data too small, not an initialized token account / mint, a read past the end, or a `@layout borsh` account whose bytes are not a valid Borsh value (AccountDidNotDeserialize) |
+| 3004 | a `@layout borsh` account too small for the value it would now hold (AccountDidNotSerialize) |
 | 3005 | not enough accounts (AccountNotEnoughKeys) |
 | 3006 | account must be writable (AccountNotMutable) |
 | 3007 | wrong owner program (AccountOwnedByWrongProgram) |
 | 3008 / 3009 | wrong program address / not executable (InvalidProgramId / InvalidProgramExecutable) |
-| 3010 | account must sign (AccountNotSigner) |
+| 3010 | account must sign (AccountNotSigner; also a new keypair account a `create(payer, null, …)` makes) |
+| 3011 | a `SystemAccount` owned by another program (AccountNotSystemOwned) |
 | 3012 | account not initialized: empty system account where a program account was expected (AccountNotInitialized) |
 | 3016 | account would grow more than 10 KiB in one instruction, or grow without a payer (AccountReallocExceedsLimit) |
 | 4102 | cast overflow (InvalidNumericConversion) |
 | 5100 / 5101 | arithmetic overflow (including shifts) / division by zero |
 | 5103 | sysvar unavailable |
-| 5104 | index out of bounds (arrays, Vecs, remaining accounts, `pop()` on an empty Vec) |
+| 5104 | index out of bounds (arrays, Vecs, remaining accounts, `pop()` on an empty Vec, `push` on a full FixedVec) |
 | 5105 | string longer than the FixedString capacity |
 | 5106 | missing or mismatched return data |
 | 5107 | event larger than 1024 bytes |