@typesol/cli 0.14.0 → 0.16.0

package/docs/mainnet.md

@@ -0,0 +1,100 @@
+# Deploy to mainnet
+
+From an empty directory to a program on Solana mainnet-beta: create, test, deploy, publish the IDL, then check that
+the deployed binary is the one your source builds. The program here is the counter that `typesol init` creates
+(13.5 KB); any TypeSOL project works the same way.
+
+You need Node.js 22.12 or later and the Agave CLI with platform-tools (see the README's Requirements).
+
+## 1. Create and test
+
+```sh
+npx @typesol/cli init my-app
+cd my-app
+npm install
+npm test
+```
+
+`npm test` runs `tests/my_app.test.ts` in LiteSVM: it compiles the program and calls it, with no validator or SOL.
+Write your program in `programs/my_app.ts` and keep the tests passing before you spend anything.
+
+## 2. Build
+
+```sh
+npx typesol build
+```
+
+This writes `target/my_app/`: the program (`my_app.so`), its Anchor IDL (`my_app.json`), a TypeScript client
+(`my_app.client.ts`) and the generated C. The first build also creates `target/deploy/my_app-keypair.json`, the
+program's address, and records the address in `typesol.json`.
+
+**Back up `target/deploy/my_app-keypair.json` now.** It is not committed (`.gitignore`), and without it you cannot
+redeploy to that address.
+
+## 3. A wallet with SOL
+
+```sh
+solana-keygen new -o ~/.config/solana/deployer.json
+solana config set --url mainnet-beta --keypair ~/.config/solana/deployer.json
+solana address
+```
+
+Send SOL to that address. Most of what a deploy costs is rent for the program's bytes, which you get back if you
+ever close the program:
+
+```sh
+solana rent $(wc -c < target/my_app/my_app.so)
+```
+
+The counter needs 0.069 SOL of rent. During the deploy the program is first written to a buffer account that holds
+the same amount again; it is returned when the deploy finishes. Fund about twice the rent plus 0.01 SOL for fees.
+
+The public mainnet RPC is rate-limited; for deploys, set `--url` (or `solana config set --url`) to your RPC
+provider's endpoint.
+
+## 4. Deploy
+
+```sh
+npx typesol deploy --dry-run   # builds and prints the solana command it will run
+npx typesol deploy
+```
+
+It runs `solana program deploy` at the address in `target/deploy/my_app-keypair.json`, with your wallet as payer and
+upgrade authority, and prints the program id. Deploying again upgrades the program in place.
+
+If a deploy stops part-way, the buffer stays behind with its SOL. The error prints the buffer's address; recover it
+with `solana program close <buffer address>`, or list yours with `solana program show --buffers`.
+
+## 5. Publish the IDL
+
+```sh
+npx typesol idl publish
+```
+
+It writes the IDL to the Program Metadata program, signed by the upgrade authority, where Anchor clients and
+explorers look for it. It costs a few thousandths of a SOL of rent.
+
+## 6. Verify
+
+```sh
+npx typesol verify my_app
+```
+
+`verify` rebuilds the program from `programs/my_app.ts`, reads the deployed one at the address in `typesol.json` from
+the cluster in your Solana CLI config, and compares the bytes. `match` means anyone with your source and the same
+TypeSOL version gets exactly the program on chain. It also prints the upgrade authority and checks the IDL you
+published in step 5. Anyone can run it against your program with `--address <program id> --url mainnet-beta`.
+
+## 7. Call it
+
+`target/my_app/my_app.client.ts` builds the program's instructions on `@solana/kit`; see [client.md](client.md).
+
+## Later
+
+- **Freeze it.** `solana program set-upgrade-authority <program id> --final` makes the program immutable. It cannot
+  be undone.
+- **Close it.** `solana program close <program id> --bypass-warning` returns the rent to the authority. The program
+  id can never be used again.
+
+A worked example: the official escrow, deployed to mainnet in TypeSOL, Pinocchio, native Rust and Anchor, with every
+transaction linked, is in the README's [On mainnet](../README.md#on-mainnet) section.

package/docs/migrate-from-anchor.md

@@ -0,0 +1,104 @@
+# Migrate from Anchor
+
+TypeSOL programs speak Anchor's wire format: the same instruction and account discriminators, Borsh arguments, an
+Anchor-format IDL, the same error numbering and event logs. A ported program can keep its clients. This page maps
+Anchor's constructs to TypeSOL's and shows the porting workflow.
+
+## Start from the IDL
+
+```sh
+anchor build                                   # in the Anchor project: target/idl/my_program.json
+npx @typesol/cli init my-program && cd my-program
+rm programs/my_program.ts tests/my_program.test.ts   # the counter template's program and test
+npx typesol port ../anchor/target/idl/my_program.json --out programs/my_program.ts
+```
+
+`typesol port` writes the account structs, enums, errors and one function per instruction with its accounts and
+arguments, each body failing with `NotPorted` until you write it. It keeps instruction discriminators, account names
+and error codes. Its notes (on stderr) list what an existing Anchor client would see differently; see
+[Account data](#account-data) below. Then, for each instruction:
+
+1. Give each account its real type: `Account<T>` / `Mut<T>` for your structs, `Init<T>` for one the instruction creates,
+   token types for token accounts (the table below).
+2. Move the constraints from `#[account(...)]` into the parameter types or the body.
+3. Port the body. Integers are `bigint`s with `n` literals, and every `+ - * / %` is checked.
+4. Test with `typesol/testing` ([test your program](test-your-program.md)), then compare the IDLs.
+
+## Accounts and constraints
+
+| Anchor | TypeSOL |
+| --- | --- |
+| `#[derive(Accounts)] struct Ctx` + `ctx.accounts.x` | the instruction's parameters, in the same order |
+| `Signer<'info>` / `#[account(mut)] Signer` | `Signer` / `Mut<Signer>` |
+| `Account<'info, T>` / `#[account(mut)]` | `Account<T>` / `Mut<T>` |
+| `#[account(init, payer = p, space = …, seeds = […], bump)]` | `Init<T>`, then `const bump = acct.create(p, ["seed", other.key])` (space is computed) |
+| `init_if_needed` | `InitIfNeeded<T>`, then `const created = acct.createIfNeeded(p, seeds)` |
+| `seeds = [b"vault", owner.key().as_ref()], bump = vault.bump` | `Seeds<Mut<Vault>, ["vault", "@owner"], "bump">` |
+| `seeds = [b"offer", offer.maker.as_ref(), offer.id.to_le_bytes().as_ref()]` | `Seeds<…, ["offer", "@offer.maker", "@offer.id"], "bump">` |
+| `has_one = owner` | `HasOne<Mut<T>, "owner">` |
+| `close = destination` | `CloseTo<Mut<T>, "destination">`, or `close(acct, destination)` in the body |
+| `address = ADMIN` | `Address<AccountInfo, "Admin1111…">` |
+| `owner = program`, `executable` | `Owner<A, "…">`, `Executable<A>` |
+| `constraint = expr @ MyError::X` | `require(expr, MyError.X)` at the start of the body |
+| `realloc = n, realloc::payer = p` | `realloc(acct, n, p)` |
+| `Option<Account<'info, T>>` | `Mut<T> \| null` (the client passes the program id to leave it out) |
+| `UncheckedAccount` / `AccountInfo` | `AccountInfo` / `Mut<AccountInfo>`: check what you rely on yourself |
+| `AccountLoader<T>` with `#[account(zero)]` | `Zeroed<T>` (TypeSOL reads every account in place: no copy to avoid) |
+| `Program<'info, System>` | `SystemProgram` |
+| `Program<'info, Token>` / `Token2022` / `Interface<'info, TokenInterface>` | `TokenProgram` / `Token2022Program` / `TokenInterface` |
+| `Account<'info, TokenAccount>` / `Account<'info, Mint>` (`InterfaceAccount`) | `TokenAccount` / `Mint` (`Mut<…>` when written) |
+| `token::mint = m, token::authority = a` | `HasOne<TokenAccount, "mint" \| "owner">` against parameters with those names |
+| `associated_token::mint = m, associated_token::authority = a` | `Ata<TokenAccount, "a", "m">`; `Ata<Init<TokenAccount>, "a", "m">` creates it |
+| `ctx.remaining_accounts` | `remainingAccounts()` |
+| `ctx.bumps.vault` | the value `create` returns, or `acct.pdaBump` |
+
+## Account data
+
+| Anchor | TypeSOL |
+| --- | --- |
+| `#[account] pub struct T { … }` | `export interface T { … }` |
+| `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)` |
+| `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),
+matches byte for byte.
+
+## Code
+
+| Anchor | TypeSOL |
+| --- | --- |
+| `pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()>` | `export function deposit(owner: Mut<Signer>, vault: Mut<Vault>, …, amount: u64): void` |
+| `-> Result<u64>` / a struct | `: u64` / a struct: sent as return data, listed in the IDL |
+| `#[error_code] enum MyError { #[msg("…")] X }` | `export enum MyError { X = "…" }` (codes from 6000, in order) |
+| `require!(c, MyError::X)`, `err!(MyError::X)` | `require(c, MyError.X)`, `require(false, MyError.X)` |
+| `require_keys_eq!(a, b)` | `require(a === b, …)` |
+| `a.checked_add(b).ok_or(…)?` | `a + b` (every operation is checked; overflow aborts with 5100) |
+| `emit!(Ev { … })` / `emit_cpi!` | `emit<Ev>({ … })` / `emitCpi<Ev>({ … }, eventAuthority, self)` |
+| `msg!("…")` | `log("…")` |
+| `Clock::get()?.unix_timestamp`, `.slot` | `now()`, `currentSlot()` |
+| `Rent::get()?.minimum_balance(n)` | `rentExempt(n)`, `minimumBalance(acct)` |
+| `system_program::transfer(CpiContext::new(…), lamports)` | `systemProgram.transfer(from, to, lamports)` |
+| `token::transfer_checked(CpiContext::new_with_signer(…, seeds), amount, decimals)` | `tokenProgram.transferChecked(from, mint, to, authority, amount, ["seed", key, bump])` |
+| `invoke_signed(&ix, &accounts, &[seeds])` | `invoke(program, [writable(a), readonly(b)], [data…], seeds)` |
+| `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` |
+
+## Tooling
+
+| Anchor | TypeSOL |
+| --- | --- |
+| `anchor init` | `typesol init` (`--template vault` / `escrow`) |
+| `anchor build` | `typesol build` (writes the IDL and a TypeScript client next to the binary) |
+| `anchor test` (mocha, bankrun) | `npm test` with `typesol/testing` in LiteSVM |
+| `anchor deploy` | `typesol deploy` ([deploy to mainnet](mainnet.md)) |
+| `anchor idl init` / `upgrade` | `typesol idl publish` |
+| `anchor verify` | `typesol verify` (reads the deployed program and IDL from the cluster) |
+| `@coral-xyz/anchor` `Program` client | the generated `<name>.client.ts` on `@solana/kit`, or Anchor's client with the IDL |

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

@@ -23,5 +23,13 @@ compiler's checks log their TypeScript location, e.g. `TypeSOL: arithmetic overf
 **Heap errors (5110) building strings** — strings are allocated on a 32 KiB heap and never freed. Build less text,
 or declare `const HEAP_SIZE_KIB = 64n` and add a ComputeBudget `requestHeapFrame` instruction to the transaction.
 
-**`typesol idl publish` fails on a local validator with "invalid instruction data"** — older validators reject a
-System instruction the current Program Metadata program uses; it works on clusters with current Agave versions.
+**`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.14.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"
+}