@typesol/cli 0.16.0 → 0.17.0

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,6 +138,11 @@ 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";
 }
 export type TokenProgramKind = "token" | "token2022" | "tokenInterface";
 export type ParamKind = {
@@ -291,6 +298,14 @@ 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;
+    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 +313,28 @@ 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: "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>;
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
 }
@@ -352,6 +379,10 @@ 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>;
     errors: ErrorDef[];
     /** Enum name -> member name -> error */
     errorEnums: Map<string, Map<string, ErrorDef>>;
@@ -374,6 +405,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 +421,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";
@@ -152,6 +153,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 +232,11 @@ 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 with a String, Vec or Option of its own: `@layout borsh` keeps Anchor's bytes.
+            const borsh = accountNames.has(def.name) && !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 +244,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

@@ -15,7 +15,8 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 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) |
@@ -26,7 +27,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 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 |

package/docs/language.md

@@ -25,6 +25,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Enums | `export enum Status { Pending, Approved }` — unit variants stored as the Borsh u8 index; `Status.Approved`, `===` |
 | Options | `best: Option<u64>` (or `u64 \| null`) — `null`, `=== null`, TypeScript narrowing; `===` between options or with a value follows JS (null equals null, empty never equals a value); empty use aborts (5108); `a ?? b` takes b only when a is empty (b runs only then; the result is an Option when b can be null), `x!` is the value or aborts with 5108; `${opt}` prints the value or `null`. Borsh `option` in arguments/events, fixed `{ is_some, value }` in account data |
 | Vecs | `entries: Vec<Entry>` as the last account field — `get`, `set`, `push(v, payer)`, `pop()`, `clear()`, `.length`; the account is resized (realloc) and rent topped up by `payer`; `Vec<u64>` arguments are read-only views; `pop()` of a Vec of structs works as a statement |
+| Anchor's account bytes | `/** @layout borsh */` on an account struct stores it as Anchor does (Borsh: a `FixedString<N>` is a String, a `FixedVec<T, N>` a Vec, an `Option` one byte when empty, and the fields after them move), so a TypeSOL program can take over accounts an Anchor program wrote and the IDL lists Anchor's own types. The instruction unpacks it into the usual fixed layout when it starts (bad bytes fail with 3003) and packs it back when it returns (3004 when the account is too small for the new value), so everything else works on it unchanged. Programs invoked from the body (CPIs) see the account's bytes as they were when the instruction started. Costs more compute than the fixed layout (the whole account is read and written each time; see the benchmarks); nested structs and list elements must be fixed-size (FixedString elements allowed); not for arguments, events, `Zeroed<T>`, `loadAccount` or a growable `Vec<T>` |
+| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed). Account data and returned structs only: arguments use `Vec<T>` |
 | Struct arguments | `order: Order`, `ids: FixedArray<u8, 4>`, `orders: Vec<Order>` — fixed layouts, Borsh-identical, validated on entry (bools, enums, option tags, string lengths, enum tags; 102) and read-only |
 | Remaining accounts | `remainingAccounts()` — `.length`, `.get(i)` → `key`, `owner`, `lamports` (writes check writability), `isSigner`, `isWritable`; `loadAccount<T>` / `loadAccountMut<T>` give checked struct views; pass them to `invoke`, one at a time or spread: `...remainingAccounts()` (each with the flags it was passed with), `...readonly(rest)` / `...writable(rest)` (all with that role), `rest.slice(a, b)` for part of them; a CPI lists at most 32 accounts (5113) |
 | Struct literals | `book.entries.push({ who: who.key, amount, status: Status.Pending, note }, who)` — every field required |
@@ -41,6 +43,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Multiple files | `import { Side, min } from "./math"` — structs, enums, constants and helpers can live in other files; only the entry file's exported functions are instructions; names are program-wide, so imports from TypeSOL files cannot be renamed; error codes number imported files first |
 | Loops | `for (let i = 0n; i < n; i++)`, `while`, `for (const x of list)` over a `Vec` or `FixedArray` (each `x` is what `list.get(i)` gives: a value, or a reference into account data for structs; the length is read again every step, as in JS), `break`, `continue` — bounded by the compute budget. Remaining accounts are iterated by index |
 | Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return `void`, a scalar or a fixed-size struct (`function at(x: u64, y: u64): Point { return { x, y }; }`: the caller gets its own copy, to bind, store with `acct.home = at(…)` / `arr.set(i, at(…))` or read as `at(…).x`); no recursion. Helpers cannot grow Vecs (only instructions know the entry size) |
+| Arrow functions | `const fee = (x: u64): u64 => x / 100n` (or `const f = function (…) {…}`) at the top level or inside a function is a helper (parameter and return types written out). A local one capturing nothing: it reads its parameters, top-level names and other functions, not the enclosing function's variables (pass them in). Functions are called, not stored or passed |
+| Generic helpers | `function max<T extends bigint>(a: T, b: T): T` — compiled once per set of types it is called with (`max(a, b)` with u64 arguments, or `max<u128>(x, 1n)` when only literals tell); a type parameter stands for an integer, boolean, Pubkey or enum. Each instance is checked like any helper; one that is never called is not compiled (TypeScript still type-checks it). Arithmetic on `T` is a `bigint` to TypeScript: `return (a + b) as T` (`as` names a type the value already has; it never converts) |
 | Evaluation order | operands and arguments are read left to right, as in JS, even when a later one changes account data (`v.length + v.pop()`) |
 | `++` `--` `+=` `-=` `*=` `/=` `%=` `&=` `\|=` `^=` `<<=` `>>=` | all checked |
 | Sysvars | `now()`, `currentSlot()`, `currentEpoch()` (clock), `minimumBalance(account)`, `rentExempt(space)` (rent) |
@@ -49,8 +53,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Events through CPI | `emitCpi<Paid>({ … }, eventAuthority, self)` with `eventAuthority: EventAuthority, self: SelfProgram` parameters — Anchor `emit_cpi!`: the event rides in a self-CPI (inner instruction), not in logs; the program accepts Anchor's event instruction (2002 / 2006 otherwise) |
 | Heap | 32 KiB by default; `const HEAP_SIZE_KIB = 64n` (32–256) lets the program use more, when clients add ComputeBudget `requestHeapFrame` |
 | Docs | JSDoc on instructions, `@param`, structs, fields and data enums becomes `docs` in the IDL |
-| Metaplex Core | `core: MplCoreProgram` — `createCollection`, `createAsset` (in a collection, PDA authorities via signerSeeds), `transferAsset`, `burnAsset` (no plugins; `null` leaves an optional account out); `coreAssetOwner(asset)`, `coreAssetCollection(asset)` |
-| Compressed NFTs | `bubblegum: BubblegumProgram` — `createTree` (client-allocated tree on SPL Account Compression), `mint` (MintV1, no collection/creators) |
+| Metaplex Core | `core: MplCoreProgram` — `createCollection`, `createAsset` (in a collection, PDA authorities via signerSeeds), `transferAsset`, `burnAsset` (`null` leaves an optional account out); plugins as a literal list after the uri (`[{ kind: "Royalties", basisPoints: 500n, creators: [{ address, percentage: 100n }] }, { kind: "PermanentFreezeDelegate", frozen: false, authority: studio.key }]`), and `addPlugin` / `updatePlugin` / `removePlugin(…, "FreezeDelegate")` with their `…CollectionPlugin` forms. Plugins: Royalties (no rule set), FreezeDelegate, BurnDelegate, TransferDelegate, UpdateDelegate, PermanentFreezeDelegate, Attributes, PermanentTransferDelegate, PermanentBurnDelegate, Edition, AddBlocker, ImmutableMetadata; `authority` is `"owner"`, `"updateAuthority"`, `"none"` or a Pubkey; `coreAssetOwner(asset)`, `coreAssetCollection(asset)` |
+| Compressed NFTs | `bubblegum: BubblegumProgram` — V1: `createTree` (client-allocated tree on SPL Account Compression), `mint` (MintV1, no collection/creators). V2 (trees on mpl-account-compression with mpl-noop): `createTreeV2`, `mintV2(…, { name, symbol, uri, sellerFeeBasisPoints, creators?, isMutable? }, { collection, authority, cpiSigner }?)` (into a Core collection that has the `BubblegumV2` plugin), `transferV2` and `burnV2` with the leaf `{ root, dataHash, creatorHash, assetDataHash?, flags?, nonce, index }` and its proof as `remainingAccounts()` / `rest.slice(a)` |
 
 ## Account parameters and the checks they emit
 
@@ -76,7 +80,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `SystemProgram`, `TokenProgram`, `Token2022Program` | exact program address |
 | `TokenInterface` | either token program |
 | `AssociatedTokenProgram` | `create` / `createIdempotent` CPIs; `associatedTokenAddress(owner, mint, tokenProgram)` |
-| `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3), optionally with `{ creators: [{ address, verified, share }], collection: mint }` after `isMutable` (1–5 creators, shares adding up to 100; only the update authority, signing, can be `verified: true`; the collection is written unverified); `metadataAddress(mint)` |
+| `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3), optionally with `{ creators: [{ address, verified, share }], collection: mint }` after `isMutable` (1–5 creators, shares adding up to 100; only the update authority, signing, can be `verified: true`; the collection is written unverified; `isCollection: true` makes the NFT a sized collection); `createMasterEditionV3(edition, mint, updateAuthority, mintAuthority, payer, metadata, tokenProgram, systemProgram, maxSupply \| null)`; `verifyCollection(authority, metadata, collectionMint, collectionMetadata, collectionMasterEdition, systemProgram, instructionsSysvar)` (Verify with CollectionV1); `metadataAddress(mint)`, `masterEditionAddress(mint)` |
 | `InstructionsSysvar`, `PythPriceUpdate`, `SwitchboardFeed` | exact address / owner program + discriminator |
 | `Program<"Address…">` | exact program address + executable |
 | `UncheckedProgram` | executable only — check `.key` yourself |
@@ -145,10 +149,10 @@ an integer literal, an argument, `acct.key` or a scalar field of an account, the
 
 ## Not supported yet
 
-Vecs anywhere but the last account field, growing an account by more than 10 KiB in one instruction, growing a Vec
+Growable `Vec`s anywhere but the last account field (use `FixedVec<T, N>`), FixedVec in arguments and events, growing an account by more than 10 KiB in one instruction, growing a Vec
 inside a helper, data-enum arguments carrying structs, Pubkeys in templates, `?.`, `**=`, `!` on anything but an Option, `switch` on
-128-bit integers, `mulDiv` beyond u64, Token Metadata collection verification, Core plugins, Bubblegum v2 / collections /
-transfers, floating point (by design), `do … while`.
+128-bit integers, `mulDiv` beyond u64, Core's MasterEdition / VerifiedCreators / Autograph plugins, royalty rule sets and external plugin adapters, Bubblegum V2 delegates / freezes / metadata updates / V1 transfers, closures (local functions reading the enclosing function's variables), functions as values (callbacks,
+`.map`), type parameters standing for structs, floating point (by design), `do … while`.
 They are rejected at compile time rather than half-supported.
 
 `Init.create` handles a PDA address someone pre-funded: it tops up rent, then allocates and assigns instead of

package/docs/migrate-from-anchor.md

@@ -60,14 +60,21 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `u8` … `u128`, `i8` … `i128`, `bool`, `Pubkey` | `u8` … `u128`, `i8` … `i128`, `boolean`, `Pubkey` |
 | `[T; N]` | `FixedArray<T, N>` |
 | `String` with `#[max_len(n)]` | `FixedString<N>`: a u32 length and N bytes, always N bytes long |
-| `Vec<T>` with `#[max_len(n)]` | `Vec<T>` as the account's last field; it grows with `push(v, payer)` |
+| `Vec<T>` with `#[max_len(n)]` | `Vec<T>` as the account's last field (it grows with `push(v, payer)`), or `FixedVec<T, n>` anywhere: a u32 length and room for n, always 4 + n × size bytes |
 | `Option<T>` | `Option<T>`: fixed size (1 + size of T) |
 | `#[derive(AnchorSerialize…)] enum` | `export enum` (unit variants) or a data enum `type A = { kind: "X"; … } \| …` |
 
-TypeSOL keeps account data at a fixed layout, so three Anchor layouts differ: a Borsh `String` is variable-length (TypeSOL
-uses `FixedString<N>`), a Borsh `Option` takes 1 byte when empty (TypeSOL always reserves the value), and a `Vec` can be
-anywhere in an Anchor struct (TypeSOL keeps it last). Accounts using them need a migration (or a new program) rather
-than an in-place upgrade. Everything else, including instruction arguments (`String`, `Option`, `Vec` are Borsh there),
+TypeSOL keeps account data at a fixed layout by default, so three Anchor layouts differ: a Borsh `String` is
+variable-length (TypeSOL uses `FixedString<N>`), a Borsh `Option` takes 1 byte when empty (TypeSOL always reserves the
+value), and a `Vec` can be anywhere in an Anchor struct (TypeSOL keeps a growable one last; a `FixedVec<T, N>` elsewhere
+always takes its full capacity, where Anchor packs the elements and moves the fields after them).
+
+To keep an Anchor program's existing accounts, mark the struct `/** @layout borsh */`: it is then stored exactly as
+Anchor stores it (`FixedString<N>` / `FixedVec<T, N>` / `Option<T>` become Borsh String / Vec / Option, N being the
+`#[max_len]`), its IDL type is Anchor's, and the upgraded program reads and writes the accounts in place. `typesol port`
+adds it for you. It costs some compute (the account is unpacked and packed in every instruction that uses it) but stays
+several times cheaper than Anchor. Accounts using them need a migration (or a new program) rather
+than an in-place upgrade, unless they use `@layout borsh`. Everything else, including instruction arguments (`String`, `Option`, `Vec` are Borsh there),
 matches byte for byte.
 
 ## Code
@@ -90,6 +97,8 @@ matches byte for byte.
 | `declare_program!(other)` / CPI to another Anchor program | `typesol cpi other.json` generates typed helpers |
 | `for x in v.iter()` | `for (const x of v)` |
 | `x.unwrap_or(d)` | `x ?? d` |
+| `fn max<T: PartialOrd>(a: T, b: T) -> T` | `function max<T extends bigint>(a: T, b: T): T` (one copy per type used) |
+| `let fee = \|x: u64\| x / 100;` (no captures) | `const fee = (x: u64): u64 => x / 100n;` |
 
 ## Tooling
 

package/docs/test-your-program.md

@@ -41,7 +41,7 @@ it("counts", async () => {
 | --- | --- |
 | `t.ok(res)` | the successful result, or throws with the program's logs |
 | `t.errorCode(res)` | the custom error code of a failed transaction: 6000 + the member's index in your error enum, or a framework code ([errors.md](errors.md)) |
-| `t.account(type, address)` | the account decoded by its IDL type (bigints, address strings), or `null` once closed |
+| `t.account(type, address)` | the account decoded by its IDL type (bigints, address strings), or `null` once closed. TypeSOL fixed layouts come back as their IDL structs: a `FixedString<N>` as `{ len, bytes }`, a `FixedVec<T, N>` as `{ len, items }` (the generated client gives strings and arrays) |
 | `t.returned(instruction, res)` | the instruction's return data: an integer, boolean, Pubkey or struct |
 | `t.balance(address)` | lamports |