@typesol/cli 0.15.0 → 0.16.0

package/docs/test-your-program.md

@@ -0,0 +1,52 @@
+# Test your program
+
+`typesol/testing` runs your program in LiteSVM, an in-process Solana runtime: no validator, no SOL, a few
+milliseconds per transaction. Projects from `typesol init` already use it in `tests/<name>.test.ts`.
+
+```ts
+import { testProgram, type TestProgram } from "typesol/testing";
+import { beforeAll, expect, it } from "vitest";
+
+let t: TestProgram;
+beforeAll(async () => {
+  t = await testProgram("counter", import.meta.url); // builds the program of typesol.json and loads it
+});
+
+it("counts", async () => {
+  const alice = await t.wallet(); // a funded keypair (10 SOL)
+  const counter = await t.pda("counter", alice); // seeds: text, addresses or keypairs, bytes, bigints (u64)
+  t.ok(await t.send(alice, t.ix("initialize", {}, { authority: alice, counter })));
+  t.ok(await t.send(alice, t.ix("increment", { by: 5n }, { authority: alice, counter })));
+  expect((await t.account<{ count: bigint }>("Counter", counter))?.count).toBe(5n);
+});
+```
+
+## Instructions
+
+`t.ix(name, args, accounts, remaining?)` builds one instruction.
+
+- **Accounts by name**, in camelCase or snake_case. Their signer and writable flags come from the IDL, and accounts
+  with a fixed address (the System Program, token programs, sysvars) are filled in, as are PDAs whose seeds are
+  constants, arguments or other accounts' keys (`t.ix("initialize", {}, { authority: alice })` derives `counter`). Pass a keypair for an account that
+  signs, an address otherwise, and `null` to leave an optional account out.
+- **Arguments as plain values:** bigints or numbers for integers, address strings for Pubkeys, `null` for an empty
+  Option, objects for structs (camelCase or snake_case fields), arrays for Vecs.
+- **Remaining accounts:** `[{ address, writable?, signer? }]`.
+
+`t.send(payer, ...ixs)` sends them in one transaction; keypairs given as accounts sign too.
+
+## Results
+
+| Helper | Gives |
+| --- | --- |
+| `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.returned(instruction, res)` | the instruction's return data: an integer, boolean, Pubkey or struct |
+| `t.balance(address)` | lamports |
+
+`t.svm`, `t.programId`, `t.idl` and `t.coder` are there for anything else, e.g. writing a mint straight into the VM
+with `t.svm.setAccount` (see the escrow template). `programHarness(svm, programId, idl)` gives the same helpers for a
+program you loaded yourself.
+
+The module needs `litesvm` and `@anchor-lang/core`, which `typesol init` adds to `devDependencies`.

package/docs/testing.md

@@ -5,7 +5,7 @@ run prints its seed; reproduce with `FUZZ_SEED=<n>`, widen with `FUZZ_RUNS` / `F
 
 | Check | Oracle | What must hold |
 | --- | --- | --- |
-| `test/fuzz-arith.test.ts` | BigInt | `+ - * / %`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
+| `test/fuzz-arith.test.ts` | BigInt | `+ - * / % **`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
 | `test/fuzz-state.test.ts` | TypeScript state model | random honest + hostile actions on vault and escrow: every outcome as predicted, balances equal the model, SOL conserved up to fees, token supply exactly conserved; random filings/decisions/resets on ledgerbook: Vec contents, account size and rent exemption equal the model |
 | `test/differential.test.ts` | Anchor twins in `bench/anchor` | identical transactions to TypeSOL and Anchor programs: same outcomes, same account contents, same wallet and token balances after every step |
 | `test/ports-*.test.ts` | the Anchor programs of solana-developers/program-examples and their tests | TypeSOL rewrites under `test/ports/` run the originals' flows and failure paths with the same outcomes, error codes and balances; each BLOCKED probe fails once its construct starts compiling, meaning that program can then be ported ([test/ports/README.md](../test/ports/README.md)) |

package/docs/troubleshooting.md

@@ -26,3 +26,10 @@ or declare `const HEAP_SIZE_KIB = 64n` and add a ComputeBudget `requestHeapFrame
 **`typesol idl publish` fails on a local validator with "invalid instruction data"** — the System Program of
 `solana-test-validator` (Agave 3.1 included) rejects a System instruction that the current Program Metadata program
 uses. Publishing works on mainnet-beta. The error shows the failing transaction's last log lines.
+
+**"instruction X needs N bytes of stack; SBF gives each function 4096"** — every function on Solana gets a 4 KiB
+stack frame, and going past it corrupts memory, so the build refuses it. Large structs and arrays copied into typed
+locals (`const q: Big = acct.big`) are the usual cause: bind them without a type (`const q = acct.big`, a reference
+into the account data) or move the work into helpers. Helpers are often inlined into their instruction, so their
+locals count toward its frame.
+

package/lib/typesol.d.ts

@@ -36,6 +36,8 @@ export interface FixedArray<T, N extends number> {
   get(index: bigint): T;
   set(index: bigint, value: T): void;
   readonly __length?: N;
+  /** `for (const x of arr)`: each element in order, as `arr.get(i)` gives it. */
+  [Symbol.iterator](): Iterator<T>;
 }
 
 /** Create a local fixed-length array filled with `fill`: `const xs = fixedArray<u64, 4>(0n)`. */
@@ -71,6 +73,8 @@ export interface Vec<T> {
   pop(): T;
   /** Remove every element, shrinking the account. */
   clear(): void;
+  /** `for (const x of vec)`: each element in order, as `vec.get(i)` gives it; the length is read again every step. */
+  [Symbol.iterator](): Iterator<T>;
 }
 
 /** One extra account passed after the declared ones. Nothing about it is checked until you check it. */
@@ -204,6 +208,13 @@ export interface AssociatedTokenProgram extends AccountMeta {
 /** The associated token account address of `owner` for `mint` under `tokenProgram`. */
 export declare function associatedTokenAddress(owner: Pubkey, mint: Pubkey, tokenProgram: Pubkey): Pubkey;
 
+/** A creator in Metaplex metadata. `verified` can only be true for the update authority when it signs. */
+export interface MetadataCreator {
+  address: Pubkey;
+  verified: boolean;
+  share: u8;
+}
+
 /** Metaplex Token Metadata (metaqbxx…). Its address is checked. */
 export interface TokenMetadataProgram extends AccountMeta {
   readonly __mpl_metadata: void;
@@ -222,6 +233,22 @@ export interface TokenMetadataProgram extends AccountMeta {
     isMutable: boolean,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  /** With creators (1–5, shares adding up to 100) and/or an unverified collection mint. */
+  createV3(
+    metadata: AccountMeta,
+    mint: AccountMeta,
+    mintAuthority: AccountMeta,
+    payer: Mut<Signer>,
+    updateAuthority: AccountMeta,
+    systemProgram: SystemProgram,
+    name: string,
+    symbol: string,
+    uri: string,
+    sellerFeeBasisPoints: u16,
+    isMutable: boolean,
+    extras: { creators?: MetadataCreator[]; collection?: Pubkey },
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
 }
 /** The canonical program address of `seeds` under `program` (Rust `Pubkey::find_program_address(seeds, program).0`). */
 export declare function findProgramAddress(seeds: Seed[], program: Pubkey): Pubkey;
@@ -602,16 +629,6 @@ interface TokenOps {
   mintTo(mint: Mint, to: TokenAccount, authority: AccountMeta, amount: u64, signerSeeds?: Seed[] | SignerSeeds): void;
   burn(from: TokenAccount, mint: Mint, authority: AccountMeta, amount: u64, signerSeeds?: Seed[] | SignerSeeds): void;
   closeAccount(account: TokenAccount, destination: AccountMeta, authority: AccountMeta, signerSeeds?: Seed[] | SignerSeeds): void;
-  /** Token-2022 only: write name/symbol/uri into a mint whose MetadataPointer points at itself (the mint needs lamports for the larger size). */
-  initializeMetadata(
-    mint: Mint,
-    updateAuthority: AccountMeta,
-    mintAuthority: AccountMeta,
-    name: string,
-    symbol: string,
-    uri: string,
-    signerSeeds?: Seed[] | SignerSeeds,
-  ): void;
   /** Let `delegate` move up to `amount` from `source`. */
   approve(source: TokenAccount, delegate: AccountMeta, owner: AccountMeta, amount: u64, signerSeeds?: Seed[] | SignerSeeds): void;
   revoke(source: TokenAccount, owner: AccountMeta, signerSeeds?: Seed[] | SignerSeeds): void;
@@ -627,18 +644,57 @@ interface TokenOps {
   initializeAccount3(account: AccountMeta, mint: AccountMeta, owner: Pubkey): void;
 }
 
+/** Operations only Token-2022 has: on Token2022Program and TokenInterface, not on TokenProgram. */
+interface Token2022Ops {
+  /** Token-2022 only: write name/symbol/uri into a mint whose MetadataPointer points at itself (the mint needs lamports for the larger size). */
+  initializeMetadata(
+    mint: Mint,
+    updateAuthority: AccountMeta,
+    mintAuthority: AccountMeta,
+    name: string,
+    symbol: string,
+    uri: string,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+
+  // Token-2022 extensions, set up on a mint created with room for them, before initializeMint2 (or, for the token
+  // account ones, before initializeAccount3). Token-2022 only: refused at compile time on TokenProgram.
+  /** TransferFeeConfig: `basisPoints` (at most 10000) of each transfer, capped at `maximumFee`. */
+  initializeTransferFeeConfig(mint: AccountMeta, configAuthority: Pubkey | null, withdrawAuthority: Pubkey | null, basisPoints: u16, maximumFee: u64): void;
+  /** MintCloseAuthority: who may close the mint once its supply is 0. */
+  initializeMintCloseAuthority(mint: AccountMeta, closeAuthority: Pubkey | null): void;
+  /** NonTransferable: tokens of this mint cannot be transferred (soul-bound). */
+  initializeNonTransferableMint(mint: AccountMeta): void;
+  /** PermanentDelegate: `delegate` may transfer or burn from any account of this mint. */
+  initializePermanentDelegate(mint: AccountMeta, delegate: Pubkey): void;
+  /** DefaultAccountState: new token accounts start frozen (true) or initialized (false). */
+  initializeDefaultAccountState(mint: AccountMeta, frozen: boolean): void;
+  /** MetadataPointer: where the mint's metadata lives (the mint itself for initializeMetadata). */
+  initializeMetadataPointer(mint: AccountMeta, authority: Pubkey | null, metadataAddress: Pubkey | null): void;
+  /** GroupPointer: where the mint's token-group data lives. */
+  initializeGroupPointer(mint: AccountMeta, authority: Pubkey | null, groupAddress: Pubkey | null): void;
+  /** GroupMemberPointer: where the mint's group-member data lives. */
+  initializeGroupMemberPointer(mint: AccountMeta, authority: Pubkey | null, memberAddress: Pubkey | null): void;
+  /** TransferHook: `programId` is invoked on every transfer of this mint. */
+  initializeTransferHook(mint: AccountMeta, authority: Pubkey | null, programId: Pubkey | null): void;
+  /** InterestBearingConfig: `rate` in basis points per year (UI amounts only; balances do not change). */
+  initializeInterestBearingMint(mint: AccountMeta, rateAuthority: Pubkey | null, rate: i16): void;
+  /** ImmutableOwner on a token account (before initializeAccount3): its owner can never change. */
+  initializeImmutableOwner(account: AccountMeta): void;
+}
+
 /** The SPL Token program (Tokenkeg). Its address is checked. */
 export interface TokenProgram extends AccountMeta, TokenOps {
   readonly __token: void;
 }
 
 /** The Token-2022 program (TokenzQdB...). Its address is checked. */
-export interface Token2022Program extends AccountMeta, TokenOps {
+export interface Token2022Program extends AccountMeta, TokenOps, Token2022Ops {
   readonly __token2022: void;
 }
 
 /** Either token program. Token accounts and mints passed alongside must belong to the program given. */
-export interface TokenInterface extends AccountMeta, TokenOps {
+export interface TokenInterface extends AccountMeta, TokenOps, Token2022Ops {
   readonly __token_interface: void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,11 @@
       "types": "./dist/profile.d.ts",
       "default": "./dist/profile.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./ts-plugin": "./ts-plugin/index.js",
     "./idl": {
       "types": "./dist/idlpublish.d.ts",
       "default": "./dist/idlpublish.js"
@@ -43,6 +48,7 @@
     "dist",
     "lib",
     "runtime",
+    "ts-plugin",
     "assets",
     "!assets/readme",
     "LICENSE",
@@ -73,6 +79,18 @@
     "@solana/kit": "^8.5.0",
     "typescript": "6.0.3"
   },
+  "peerDependencies": {
+    "@anchor-lang/core": "^1.2.1",
+    "litesvm": "^1.6.1"
+  },
+  "peerDependenciesMeta": {
+    "@anchor-lang/core": {
+      "optional": true
+    },
+    "litesvm": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@anchor-lang/core": "1.2.1",
     "@noble/curves": "^2.4.0",

package/runtime/typesol_rt.h

@@ -1211,15 +1211,19 @@ static inline uint64_t ts_metadata_address(const SolPubkey *mint, SolPubkey *out
 
 /*
  * Metaplex CreateMetadataAccountV3 (instruction 33): DataV2 { name, symbol, uri, seller_fee_basis_points u16,
- * creators None, collection None, uses None }, is_mutable bool, collection_details None.
+ * creators Option<Vec<Creator>>, collection Option<Collection>, uses None }, is_mutable bool, collection_details None.
+ * `creators` holds `ncreators` packed Creator records (address, verified, share: 34 bytes); ncreators < 0 is None.
+ * `collection` (NULL for None) is written unverified, as Metaplex requires at creation.
  * Accounts: metadata (w), mint, mint authority (s), payer (ws), update authority, system program.
  */
 static inline uint64_t ts_mpl_create_v3(TsParams *params, const TsAccount *program, TsAccount *metadata,
                                         TsAccount *mint, TsAccount *mint_authority, TsAccount *payer,
                                         TsAccount *update_authority, TsAccount *system, TS_Str name, TS_Str symbol,
-                                        TS_Str uri, uint16_t fee_bps, bool is_mutable, const SolSignerSeed *seeds, int n) {
+                                        TS_Str uri, uint16_t fee_bps, bool is_mutable, const uint8_t *creators, int ncreators,
+                                        const SolPubkey *collection, const SolSignerSeed *seeds, int n) {
   uint8_t *data;
-  TS_TRY(ts_alloc(1 + 12 + name.len + symbol.len + uri.len + 2 + 3 + 1 + 1, &data));
+  uint64_t ncr = ncreators > 0 ? (uint64_t)ncreators : 0;
+  TS_TRY(ts_alloc(1 + 12 + name.len + symbol.len + uri.len + 2 + (1 + 4 + 34 * ncr) + (1 + 33) + 1 + 1 + 1, &data));
   uint64_t at = 0;
   data[at++] = 33;
   ts_put_str(data, &at, name);
@@ -1227,8 +1231,24 @@ static inline uint64_t ts_mpl_create_v3(TsParams *params, const TsAccount *progr
   ts_put_str(data, &at, uri);
   ts_memcpy(data + at, &fee_bps, 2);
   at += 2;
-  data[at++] = 0; /* creators: None */
-  data[at++] = 0; /* collection: None */
+  if (ncreators < 0) {
+    data[at++] = 0; /* creators: None */
+  } else {
+    data[at++] = 1;
+    uint32_t count = (uint32_t)ncreators;
+    ts_memcpy(data + at, &count, 4);
+    at += 4;
+    ts_memcpy(data + at, creators, 34 * ncr);
+    at += 34 * ncr;
+  }
+  if (collection) {
+    data[at++] = 1;
+    data[at++] = 0; /* verified: false */
+    ts_memcpy(data + at, collection, 32);
+    at += 32;
+  } else {
+    data[at++] = 0; /* collection: None */
+  }
   data[at++] = 0; /* uses: None */
   data[at++] = is_mutable ? 1 : 0;
   data[at++] = 0; /* collection_details: None */

package/ts-plugin/index.js

@@ -0,0 +1,112 @@
+// TypeScript language-service plugin: TypeSOL's own errors in the editor, next to TypeScript's.
+//
+//   programs/tsconfig.json: { "compilerOptions": { …, "plugins": [{ "name": "typesol/ts-plugin" }] } }
+//
+// For each program entry of the project (typesol.json), once TypeScript itself reports no errors, it runs
+// `typesol check --json --stdin` on the editor's text (unsaved changes included) and shows what the compiler refuses
+// (an unsupported construct, a missing account constraint…) at its line and column. Editors load tsconfig plugins
+// from the workspace's TypeScript (VS Code: "TypeScript: Select TypeScript Version" → "Use Workspace Version").
+// CommonJS on purpose: tsserver loads plugins with require().
+"use strict";
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CLI = path.join(__dirname, "..", "dist", "cli.js");
+const CODE = 9900;
+
+/** The program entry files of the typesol.json at or above `dir` (absolute), or an empty set. */
+function entriesNear(dir) {
+  for (let d = dir; ; d = path.dirname(d)) {
+    const config = path.join(d, "typesol.json");
+    if (fs.existsSync(config)) {
+      try {
+        const programs = JSON.parse(fs.readFileSync(config, "utf8")).programs || {};
+        return new Set(Object.values(programs).map((p) => path.resolve(d, typeof p === "string" ? p : p.path)));
+      } catch {
+        return new Set();
+      }
+    }
+    if (path.dirname(d) === d) return new Set();
+  }
+}
+
+function init({ typescript: ts }) {
+  function create(info) {
+    const ls = info.languageService;
+    const log = (m) => info.project.projectService.logger.info(`[typesol] ${m}`);
+    const cache = new Map(); // fileName -> { text, found }
+
+    /** The entry's text plus the modification times of the .ts files beside it (its imports usually live there). */
+    function key(fileName, sf) {
+      const dir = path.dirname(path.resolve(fileName));
+      let stamps = "";
+      try {
+        for (const f of fs.readdirSync(dir).sort())
+          if (f.endsWith(".ts") && path.join(dir, f) !== path.resolve(fileName)) stamps += `${f}:${fs.statSync(path.join(dir, f)).mtimeMs};`;
+      } catch {
+        stamps = "";
+      }
+      return `${stamps}\n${sf.text}`;
+    }
+
+    function typesolDiagnostics(fileName, sf) {
+      const k = key(fileName, sf);
+      const hit = cache.get(fileName);
+      if (hit && hit.key === k) return hit.found;
+      let found = [];
+      try {
+        const out = execFileSync(process.execPath, [CLI, "check", fileName, "--json", "--stdin"], {
+          input: sf.text,
+          encoding: "utf8",
+          timeout: 15000,
+          // tsserver may run inside an editor's Electron: make it behave as plain Node for the child.
+          env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        found = JSON.parse(out).diagnostics;
+      } catch (e) {
+        // Exit 1 with JSON on stdout means diagnostics; anything else is a crash worth logging, not showing.
+        try {
+          found = JSON.parse(String(e.stdout)).diagnostics;
+        } catch {
+          log(`check failed for ${fileName}: ${e.message}`);
+          found = [];
+        }
+      }
+      cache.set(fileName, { key: k, found });
+      return found;
+    }
+
+    const proxy = Object.create(null);
+    for (const k of Object.keys(ls)) proxy[k] = (...args) => ls[k](...args);
+    proxy.getSemanticDiagnostics = (fileName) => {
+      const prior = ls.getSemanticDiagnostics(fileName);
+      if (prior.some((d) => d.category === ts.DiagnosticCategory.Error)) return prior; // TypeScript's errors first
+      if (!entriesNear(path.dirname(path.resolve(fileName))).has(path.resolve(fileName))) return prior;
+      const sf = ls.getProgram() && ls.getProgram().getSourceFile(fileName);
+      if (!sf) return prior;
+      const own = typesolDiagnostics(fileName, sf)
+        .filter((d) => path.resolve(d.file) === path.resolve(fileName))
+        .map((d) => {
+          const line = Math.max(0, Math.min(d.line - 1, sf.getLineStarts().length - 1));
+          const start = Math.min(sf.getPositionOfLineAndCharacter(line, 0) + Math.max(0, d.column - 1), sf.end);
+          const word = /^[\w$]+/.exec(sf.text.slice(start));
+          return {
+            file: sf,
+            start,
+            length: word ? word[0].length : 1,
+            messageText: d.message,
+            category: ts.DiagnosticCategory.Error,
+            code: CODE,
+            source: "typesol",
+          };
+        });
+      return [...prior, ...own];
+    };
+    return proxy;
+  }
+  return { create };
+}
+
+module.exports = init;

package/ts-plugin/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "main": "index.js"
+}