@typesol/cli 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,127 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 0.18.0 — 2026-10-28
+
+The remaining Anchor differences, closed: Anchor's argument structs (Strings, Vecs, Options and enums in Borsh),
+keypair `init` with `space`, `init` of mints with Token-2022 extensions and of token accounts, `Vec<String>`
+arguments, `SystemAccount`, string return values, and the Token-2022 and Token Metadata instructions programs call.
+Closures, list callbacks and more everyday TypeScript; the rest of Bubblegum and Core. 26 of the 46 official
+examples are now full ports. Existing programs keep their layouts and error codes (2018 and 3011 are new, raised only
+by the new `Init<Mint>` and `SystemAccount` checks). Not externally audited (see SECURITY.md).
+
+### Added
+Anchor accounts and arguments:
+- `@layout borsh` structs as whole instruction arguments, return values and events, in Anchor's Borsh bytes (a
+  FixedString is a String, a FixedVec a Vec, an Option one byte when empty). Arguments are checked as Borsh
+  deserialization does, UTF-8 included (102 otherwise). `return vault` returns a whole struct account.
+- `@layout borsh` structs used as arguments, return values or events may hold `string` fields and data enums (with or
+  without strings), as Anchor argument structs do; Borsh accounts may hold data enums without strings.
+- `acct.create(payer, null)` on `Init<T>`: Anchor's `init` of a keypair account (it must sign; 3010 otherwise), and an
+  optional third argument for Anchor's `space = …` on `create` / `createIfNeeded`.
+- Mint extensions on `Init<Mint>`: `mint.create(payer, seeds | null, decimals, authority, freeze, { … })` with
+  transferFee, closeAuthority, defaultAccountState, nonTransferable, interestBearing, permanentDelegate, transferHook,
+  metadataPointer, groupPointer and groupMemberPointer (Anchor's `extensions::…`).
+- `Init<Mint>` / `InitIfNeeded<Mint>` with `mint.create(payer, seeds | null, decimals, mintAuthority, freezeAuthority)`
+  and `Init<TokenAccount>` / `InitIfNeeded<TokenAccount>` (without `Ata<…>`) with `vault.create(payer, seeds | null,
+  mint, authority)`: Anchor's `init` with `mint::` / `token::` constraints, at a PDA of this program or (with `null`) a
+  new keypair account that signs, under SPL Token or Token-2022 (token accounts sized with GetAccountDataSize). The
+  `createIfNeeded` forms check an existing account like Anchor's `init_if_needed` (2014 / 2015 / 2016 / 2017 and the
+  new 2018 ConstraintMintDecimals). The IDL marks keypair-created accounts as signers.
+- `SystemAccount` / `Mut<SystemAccount>`: Anchor's `SystemAccount`, refused with 3011 (AccountNotSystemOwned) when
+  another program owns it.
+- `Vec<string>` instruction arguments (Anchor's `Vec<String>`): `.get(i)`, `.length`, `for … of`, list callbacks,
+  helper parameters, storing into `FixedVec<FixedString<N>, M>`, and re-encoding through `invoke`; each string is
+  checked as UTF-8 on entry (102).
+- Helpers and instructions can return `string` (an instruction's is Borsh String return data).
+- `acct.key` of an `Init<…>` account before it is created (the address is known; Anchor seeds use it that way).
+- `mint.create(…, tokenProgram)` / `vault.create(…, tokenProgram)`: an explicit token program, for instructions that
+  take more than one.
+
+Language:
+- Closures: a local function that reads or writes the enclosing function's variables is expanded where it is called,
+  with the names it was declared with (a block at the call that declares the same name does not change it), struct
+  parameters by reference and `return` leaving the closure. Recursion and storing / returning closures are refused.
+- List callbacks on Vec, FixedArray, FixedVec and Vec arguments: `forEach`, `some`, `every`, `find`, `findIndex`,
+  `reduce`, `includes`, `indexOf`, expanded into loops with the arrow written at the call.
+- Helpers can take function parameters (`f: (x: u64) => u64`): compiled once per named function passed.
+- `do … while` loops (`continue` goes to the test).
+- `x **= n` (the target must not call a function: it is read and written).
+- `switch` on 128-bit integers (the case is picked with comparisons, then switched on as usual, fallthrough included).
+- `?.` on optional accounts (`acct?.field`) and on `Option<struct>` fields (`x.home?.field`): an Option, empty when the
+  account was left out or the option is empty; use it with `??`.
+- `acct!` on optional accounts (fails with 5115 when it was left out), Pubkeys / Hashes in template strings (base58),
+  and data-enum arguments whose variants carry fixed-size structs or arrays.
+- Type parameters standing for fixed-size structs (`pick<Point>(…)`, or taken from struct arguments), and `cond ? a : b`
+  for struct values (places, literals or calls).
+- Growable `Vec<T>` `push` / `pop` / `clear` inside helpers that take the account as `Mut<T>` (with its payer and
+  SystemProgram, as in instructions).
+- `mulDiv` / `mulDivCeil` on u128 through a 256-bit product (all three u128; literals take that type).
+
+CPI:
+- Token-2022 extension instructions: `updateDefaultAccountState`, `updateTransferHook`, `enableRequiredMemoTransfers` /
+  `disableRequiredMemoTransfers`, `updateInterestRate`, `transferCheckedWithFee`, `harvestWithheldTokensToMint`,
+  `withdrawWithheldTokensFromMint`, `setTransferFee`; the Token Metadata interface: `updateMetadataField`,
+  `removeMetadataKey`, `updateMetadataAuthority`, `emitMetadata`; `closeAccount` of a mint; `mintTo` /
+  `initializeMetadata` on a mint created earlier in the instruction; `isTransferring(tokenAccount)` and
+  `transferHookAuthority(mint)`.
+- Metaplex Core plugin values: MasterEdition, VerifiedCreators, Autograph, FreezeExecute, PermanentFreezeExecute, and
+  royalty rule sets (`ruleSet: { programAllowList | programDenyList }`).
+- Bubblegum: `delegateV2`, `freezeV2`, `thawV2`, `setNonTransferableV2`, `updateMetadataV2`, `verifyCreatorV2`,
+  `unverifyCreatorV2`, `setCollectionV2`, and the V1 `transfer`, `burn`, `delegate`. Checked on the real programs with
+  every leaf recomputed: verify → delegate → freeze (a frozen leaf is refused) → thaw → rename, unverify, moving a leaf
+  into a collection, soulbinding a collection's leaf, and a V1 transfer signed by a PDA owner, delegate and burn.
+
+### Fixed
+- Bubblegum leaf fields that may be null at run time (`assetDataHash: Hash | null`, `flags`) are sent as Borsh Options;
+  a null aborted the instruction before.
+
+## 0.17.0 — 2026-10-28
+
+Anchor's account bytes on request (`@layout borsh`, so a TypeSOL program can take over an Anchor program's accounts
+without a migration), lists with a fixed capacity anywhere in account data (`FixedVec`), arrow functions and generic
+helpers, Metaplex collection verification, Core plugins and Bubblegum V2, and a faster UTF-8 check. Existing programs
+keep their layouts and error codes (3004 is new, raised only by `@layout borsh` accounts). Not externally audited (see
+SECURITY.md).
+
+### Added
+- `/** @layout borsh */` on an account struct stores it with Anchor's bytes (Borsh String / Vec / Option for
+  `FixedString` / `FixedVec` / `Option`), so a TypeSOL program can take over an Anchor program's accounts without a
+  migration; its IDL lists Anchor's own types. An instruction unpacks the account into the fixed layout when it starts
+  and packs it back when it returns (3003 for bytes that are not a valid value, 3004 when the account is too small).
+  Checked byte for byte against an Anchor twin, including switching programs in the middle of a sequence.
+  `typesol port` marks Anchor account structs that need it.
+- `FixedVec<T, N>`: a list with room for N elements (u32 length + N slots, like `FixedString<N>`) as any account field,
+  several per struct and in nested structs, with `get` / `set` / `push` / `pop` / `clear` / `.length` / `for … of`;
+  `push` on a full one fails with 5104, `fixedVec([…])` writes a whole one. The IDL describes each as a
+  `FixedVec<N>_<T>` struct `{ len, items }`; the generated client reads and writes them as arrays. The
+  basics/favorites port uses one.
+- Bubblegum V2: `createTreeV2`, `mintV2` (optionally into a Metaplex Core collection), `transferV2` and `burnV2`, which
+  take the leaf (root, data and creator hashes, nonce, index) and pass its Merkle proof on from the remaining accounts;
+  the Core `BubblegumV2` collection plugin. Checked against Bubblegum, mpl-account-compression, mpl-noop and Core
+  (`pnpm fetch:programs` now fetches the mpl-account-compression pair too).
+- Metaplex Core plugins: a literal plugin list in `createAsset` / `createCollection` (Royalties, freeze / burn / transfer /
+  update delegates and their permanent forms, Attributes, Edition, AddBlocker, ImmutableMetadata, each with an optional
+  authority), and `addPlugin`, `updatePlugin`, `removePlugin` with their collection forms, checked against the real Core
+  program (a frozen asset cannot move until it is thawed).
+- Arrow functions: `const f = (x: u64): u64 => …` (and `const f = function (…) {…}`) at the top level or inside a
+  function is a helper. Local ones capture nothing (a closure over the enclosing function's variables is refused with
+  the name it reads); functions are called, not passed around.
+- Generic helpers: `function max<T extends bigint>(a: T, b: T): T` compiles once per set of types it is called with,
+  inferred from the arguments or written out (`max<u128>(x, 1n)`); type parameters stand for integers, booleans,
+  Pubkeys or enums.
+- `x as T` (and `satisfies`): names a type the value already has, never a conversion; mainly `return (a + b) as T`
+  in a generic helper.
+- Metaplex collections: `createV3`'s `isCollection: true` (CollectionDetails::V1), `createMasterEditionV3(…, maxSupply | null)`,
+  `verifyCollection(…)` (Verify with CollectionV1) and `masterEditionAddress(mint)`. The tokens/nft-operations port now
+  uses them instead of hand-encoded `invoke`s, checked against the real Token Metadata program.
+
+### Changed
+- IDLs no longer list `FixedString*` / `FixedOption_*` / `FixedVec*` helper types that nothing in them refers to
+  (for example an `Option` used only as an instruction argument, which is Borsh there).
+- UTF-8 checks of strings run eight ASCII bytes at a time: every official-example instruction with a string argument
+  gets cheaper (create_token_mint 40,919 → 39,828 CU, set_favorites 4,282 → 4,195).
+
 ## 0.16.0 — 2026-10-28
 
 Everyday TypeScript that Anchor developers reach for (`for … of`, `??`, destructuring, `**`, structs returned from

package/README.md

@@ -189,10 +189,10 @@ Runtime failures point back to your source: `Error 6000 Unauthorized (counter.ts
 
 | | |
 | --- | --- |
-| **Accounts** | `Signer`, `Account<T>`, `Mut<T>`, `Init<T>`, `InitIfNeeded<T>` (PDAs and associated token accounts), `Zeroed<T>` (up to 10 MiB), optional accounts (`A \| null`), token accounts and mints, programs, sysvars |
+| **Accounts** | `Signer`, `Account<T>`, `Mut<T>`, `Init<T>`, `InitIfNeeded<T>` (PDAs or keypair accounts, with Anchor's `space`; mints, token accounts and associated token accounts), `Zeroed<T>` (up to 10 MiB), optional accounts (`A \| null`), token accounts and mints, `SystemAccount`, programs, sysvars |
 | **Constraints** | `HasOne`, `Seeds` (also from account fields and under another program; `pdaBump` like `ctx.bumps`), `CloseTo`, `Ata`, `Address`, `Owner`, `Executable`. They are checked before the body runs and recorded in the IDL |
-| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account |
-| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too) across multiple files |
+| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account, `FixedVec` lists anywhere, and Anchor's own byte layout (`@layout borsh`) to take over existing Anchor accounts and to pass, return and emit structs with String / Vec / Option fields as Anchor does |
+| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too, arrow functions, closures, function arguments, generics), list callbacks (`some`, `find`, `reduce`, …) across multiple files |
 | **CPIs** | System, SPL Token, Token-2022 (including extension reads and metadata), ATA, Metaplex Token Metadata, Core, Bubblegum. Generic `invoke` with PDA signing, return data, and typed bindings generated from any Anchor IDL (`typesol cpi`) |
 | **Events** | `emit` (log-based) and `emitCpi` (Anchor `emit_cpi!`, through a self-CPI) |
 | **Crypto & oracles** | `sha256`, `keccak256`, Merkle proofs, Ed25519 and secp256k1 signature checks, Pyth pull oracle, Switchboard |
@@ -306,7 +306,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.16).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.18).** Releases follow the organization's
 [versioning policy](https://github.com/typesol/.github/blob/main/VERSIONING.md); [CHANGELOG.md](CHANGELOG.md) lists every
 change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.

package/dist/clientgen.js

@@ -39,16 +39,19 @@ export const TYPESOL_ERRORS = {
     2015: "ConstraintTokenOwner",
     2016: "ConstraintMintMintAuthority",
     2017: "ConstraintMintFreezeAuthority",
+    2018: "ConstraintMintDecimals",
     2040: "ConstraintDuplicateMutableAccount",
     3000: "AccountDiscriminatorAlreadySet",
     3002: "AccountDiscriminatorMismatch",
     3003: "AccountDidNotDeserialize",
+    3004: "AccountDidNotSerialize",
     3005: "AccountNotEnoughKeys",
     3006: "AccountNotMutable",
     3007: "AccountOwnedByWrongProgram",
     3008: "InvalidProgramId",
     3009: "InvalidProgramExecutable",
     3010: "AccountNotSigner",
+    3011: "AccountNotSystemOwned",
     3012: "AccountNotInitialized",
     3016: "AccountReallocExceedsLimit",
     4102: "InvalidNumericConversion",
@@ -383,6 +386,8 @@ export function generateClient(idl, opts = {}) {
         const arrayLen = (t) => (typeof t === "object" && t.array ? Number(t.array[1]) : NaN);
         if (/^FixedString\d+$/.test(n) && f[0].name === "len" && Number.isInteger(arrayLen(f[1].type)))
             return { kind: "fstring", cap: arrayLen(f[1].type) };
+        if (/^FixedVec\d+_/.test(n) && f[0].name === "len" && f[1].name === "items" && Number.isInteger(arrayLen(f[1].type)))
+            return { kind: "fvec", elem: f[1].type.array[0], cap: arrayLen(f[1].type) };
         if (n.startsWith("FixedOption_") && f[0].name === "is_some")
             return { kind: "foption", inner: f[1].type };
         if (n.startsWith("FixedEnum_") && f[0].name === "tag" && defs.has(n.slice("FixedEnum_".length)) && Number.isInteger(arrayLen(f[1].type)))
@@ -476,6 +481,8 @@ export function generateClient(idl, opts = {}) {
         const s = special(n);
         if (s?.kind === "fstring")
             return "string";
+        if (s?.kind === "fvec")
+            return `Array<${tsType(s.elem, dir)}>`;
         if (s?.kind === "foption")
             return `${tsType(s.inner, dir)} | null`;
         if (s?.kind === "fenum")
@@ -484,6 +491,7 @@ export function generateClient(idl, opts = {}) {
     }
     let needsFixedString = false;
     let needsFixedOption = false;
+    let needsFixedVec = false;
     let needsUnitEnum = false;
     function codec(t) {
         if (typeof t === "string") {
@@ -525,6 +533,11 @@ export function generateClient(idl, opts = {}) {
         const s = special(n);
         if (s?.kind === "fstring")
             return ((needsFixedString = true), `fixedString(${s.cap})`);
+        if (s?.kind === "fvec") {
+            if (idlSize(s.elem) === undefined)
+                throw new ClientIdlError(`${n}: the elements have no fixed size`);
+            return ((needsFixedVec = true), `fixedVec(${codec(s.elem)}, ${idlSize(s.elem)}, ${s.cap})`);
+        }
         if (s?.kind === "foption") {
             const size = idlSize(s.inner);
             if (size === undefined)
@@ -560,6 +573,10 @@ export function generateClient(idl, opts = {}) {
         const sp = special(n);
         if (sp?.kind === "fstring")
             return 4 + sp.cap;
+        if (sp?.kind === "fvec") {
+            const e = idlSize(sp.elem);
+            return e === undefined ? undefined : 4 + e * sp.cap;
+        }
         if (sp?.kind === "fenum")
             return sp.size;
         if (sp?.kind === "foption") {
@@ -982,6 +999,28 @@ export function generateClient(idl, opts = {}) {
                 `  });`,
             ],
         });
+    if (needsFixedVec)
+        helperDefs.push({
+            name: "fixedVec",
+            lines: [
+                `/** TypeSOL FixedVec<T, N> in account data: u32 length, then room for N elements (unused ones zero). */`,
+                `const fixedVec = <From, To extends From>(item: Codec<From, To>, size: number, cap: number): Codec<From[], To[]> =>`,
+                `  createCodec<From[], To[]>({`,
+                `    fixedSize: 4 + size * cap,`,
+                `    write: (value, bytes, offset) => {`,
+                `      if (value.length > cap) throw new Error(value.length + " elements; the field holds " + cap);`,
+                `      bytes.fill(0, offset, offset + 4 + size * cap);`,
+                `      getU32Codec().write(value.length, bytes, offset);`,
+                `      value.forEach((v, i) => item.write(v, bytes, offset + 4 + i * size));`,
+                `      return offset + 4 + size * cap;`,
+                `    },`,
+                `    read: (bytes, offset) => {`,
+                `      const n = Math.min(getU32Codec().read(bytes, offset)[0], cap);`,
+                `      return [Array.from({ length: n }, (_, i) => item.read(bytes, offset + 4 + i * size)[0]), offset + 4 + size * cap];`,
+                `    },`,
+                `  });`,
+            ],
+        });
     if (needsUnitEnum)
         helperDefs.push({
             name: "unitEnum",

package/dist/compiler/analyze.d.ts

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { Reporter } from "./diagnostics.js";
-import { type DataEnumDef, type EnumDef, type ProgramModel, type ScalarType, type StructDef, type ValueType, isScalar } from "./model.js";
+import { type DataEnumDef, type EnumDef, type GenericHelper, type Helper, type ProgramModel, type ScalarType, type StructDef, type ValueType, isScalar } from "./model.js";
 export declare const LIB_PATH: string;
 /** Why a name cannot be used as a C member, or undefined when it can. */
 export declare function cNameProblem(name: string): string | undefined;
@@ -11,6 +11,8 @@ export declare const MAX_RETURN_DATA = 1024;
 export declare const MAX_CPI_ALLOCATION: number;
 export interface Analysis {
     model: ProgramModel;
+    /** A generic helper's instance for these type arguments (analyzed once, then kept in `model.helpers`). */
+    instantiate(g: GenericHelper, typeArgs: TypeArg[], fnArgs?: string[]): Helper;
     /** TypeScript's checker: used for narrowing (which variant a data-enum value is in a branch). */
     checker: ts.TypeChecker;
     sourceFile: ts.SourceFile;
@@ -20,9 +22,20 @@ export interface Analysis {
     imports: Map<string, string>;
     reporter: Reporter;
 }
+/** What a generic helper's type parameter stands for: a scalar, or a fixed-size struct. */
+export type TypeArg = ScalarType | {
+    kind: "struct";
+    name: string;
+};
+/** A struct named by a type reference, through the type parameters of a generic helper's instance. */
+export declare function structNameOf(node: ts.TypeNode, scope: Pick<TypeScope, "structArgs">): string | undefined;
 /** What type resolution needs: imports, unit enums, and where to record Option<T> uses. */
 export interface TypeScope {
     imports: Map<string, string>;
+    /** Inside a generic helper's instance: type parameter -> the type it stands for. */
+    typeArgs?: Map<string, ScalarType>;
+    /** Inside a generic helper's instance: type parameter -> the struct it stands for. */
+    structArgs?: Map<string, string>;
     enums: Map<string, EnumDef>;
     dataEnums?: Map<string, DataEnumDef>;
     options: Map<string, ScalarType | {
@@ -49,4 +62,6 @@ export declare function resolveOptionType(node: ts.TypeNode, scope: TypeScope):
 }) | undefined;
 /** Values a local, argument or helper parameter can hold. */
 export declare function resolveValueType(node: ts.TypeNode, scope: TypeScope, allowVec?: boolean): ValueType | undefined;
+/** The helper (or generic) a call's callee names: a local function by its declaration, others by name. */
+export declare function calleeName(callee: ts.Identifier, decls: Map<ts.Node, string>, checker: ts.TypeChecker): string | undefined;
 export { isScalar };