@typesol/cli 0.15.0 → 0.17.0

package/docs/migrate-from-anchor.md

@@ -0,0 +1,113 @@
+# 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)`), 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 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
+
+| 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` |
+| `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
+
+| 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. 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 |
+
+`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,8 +73,28 @@ 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>;
 }
 
+/**
+ * A list stored inline with room for N elements: a u32 length, then N slots (Anchor `Vec<T>` with `#[max_len(N)]`, but
+ * always 4 + N × size(T) bytes). Unlike `Vec<T>` it can be any field, any number of times, and in nested structs;
+ * `push` fails (5104) when it is full. Write a whole one with `fixedVec([a, b])`.
+ */
+export interface FixedVec<T, N extends number> {
+  readonly length: u64;
+  get(index: bigint): T;
+  set(index: bigint, value: T): void;
+  push(value: T): void;
+  pop(): T;
+  clear(): void;
+  [Symbol.iterator](): Iterator<T>;
+  readonly __capacity?: N;
+}
+/** A FixedVec value holding these elements (`acct.owners = fixedVec([a, b])`, `{ owners: fixedVec([]) }`). */
+export declare function fixedVec<T>(items: T[]): FixedVec<T, never>;
+
 /** One extra account passed after the declared ones. Nothing about it is checked until you check it. */
 export interface RemainingAccount {
   readonly key: Pubkey;
@@ -204,6 +226,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,7 +251,58 @@ export interface TokenMetadataProgram extends AccountMeta {
     isMutable: boolean,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  /**
+   * With creators (1–5, shares adding up to 100), an unverified collection mint, and/or `isCollection: true`
+   * (CollectionDetails::V1: this NFT is a sized collection other NFTs are verified into).
+   */
+  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; isCollection?: boolean },
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /**
+   * CreateMasterEditionV3: makes `mint` (supply 1, decimals 0) a master edition; the mint and freeze authorities move
+   * to the edition. `maxSupply` 0n is a one of one, `null` allows unlimited prints.
+   */
+  createMasterEditionV3(
+    edition: AccountMeta,
+    mint: AccountMeta,
+    updateAuthority: AccountMeta,
+    mintAuthority: AccountMeta,
+    payer: Mut<Signer>,
+    metadata: AccountMeta,
+    tokenProgram: TokenProgram,
+    systemProgram: SystemProgram,
+    maxSupply: u64 | null,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /**
+   * Verify with CollectionV1: marks `metadata`'s collection (set with createV3's `collection`) verified. `authority` is
+   * the collection's update authority; the collection is a master edition created with `isCollection: true`.
+   */
+  verifyCollection(
+    authority: AccountMeta,
+    metadata: AccountMeta,
+    collectionMint: AccountMeta,
+    collectionMetadata: AccountMeta,
+    collectionMasterEdition: AccountMeta,
+    systemProgram: SystemProgram,
+    instructionsSysvar: AccountMeta,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
 }
+/** The Metaplex master edition address of a mint (PDA ["metadata", program, mint, "edition"]). */
+export declare function masterEditionAddress(mint: Pubkey): Pubkey;
 /** 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;
 /** The Metaplex metadata account address of a mint. */
@@ -446,9 +526,36 @@ export declare function emitCpi<T>(event: T, eventAuthority: EventAuthority, sel
  * account out. Accounts that sign (the new asset/collection, authorities) are keypair Signers, or PDAs of this
  * program covered by `signerSeeds`.
  */
+/**
+ * Who manages a Metaplex Core plugin: `"owner"`, `"updateAuthority"`, `"none"` (nobody: fixed), or an address. Left out,
+ * the plugin type's default (the owner for owner-managed plugins, the update authority for the others).
+ */
+export type CorePluginAuthority = "none" | "owner" | "updateAuthority" | Pubkey;
+/** A Metaplex Core plugin, written as an object literal (Core's Plugin enum, with its authority when it is added). */
+export type CorePlugin = (
+  | { kind: "Royalties"; basisPoints: u16; creators: { address: Pubkey; percentage: u8 }[] }
+  | { kind: "FreezeDelegate"; frozen: boolean }
+  | { kind: "BurnDelegate" }
+  | { kind: "TransferDelegate" }
+  | { kind: "UpdateDelegate"; additionalDelegates?: Pubkey[] }
+  | { kind: "PermanentFreezeDelegate"; frozen: boolean }
+  | { kind: "Attributes"; attributes: { key: string; value: string }[] }
+  | { kind: "PermanentTransferDelegate" }
+  | { kind: "PermanentBurnDelegate" }
+  | { kind: "Edition"; number: u32 }
+  | { kind: "AddBlocker" }
+  | { kind: "ImmutableMetadata" }
+  /** On a collection: lets Bubblegum mint compressed NFTs into it (mintV2 with a collection). */
+  | { kind: "BubblegumV2" }
+) & { authority?: CorePluginAuthority };
+export type CorePluginKind = CorePlugin["kind"] | "MasterEdition" | "VerifiedCreators" | "Autograph";
+
 export interface MplCoreProgram extends AccountMeta {
   readonly __mpl_core: void;
-  /** CreateV1. In a collection, `authority` is the collection's update authority; `owner` defaults to the payer. */
+  /**
+   * CreateV1. In a collection, `authority` is the collection's update authority; `owner` defaults to the payer.
+   * `plugins` (a literal list, one of each kind) are created with the asset.
+   */
   createAsset(
     asset: AccountMeta,
     collection: AccountMeta | null,
@@ -460,6 +567,18 @@ export interface MplCoreProgram extends AccountMeta {
     uri: string,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  createAsset(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    authority: AccountMeta | null,
+    payer: Mut<Signer>,
+    owner: AccountMeta | null,
+    systemProgram: SystemProgram,
+    name: string,
+    uri: string,
+    plugins: CorePlugin[],
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
   createCollection(
     collection: AccountMeta,
     updateAuthority: AccountMeta | null,
@@ -469,6 +588,70 @@ export interface MplCoreProgram extends AccountMeta {
     uri: string,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  /** With plugins every asset of the collection inherits (Royalties, PermanentFreezeDelegate, …). */
+  createCollection(
+    collection: AccountMeta,
+    updateAuthority: AccountMeta | null,
+    payer: Mut<Signer>,
+    systemProgram: SystemProgram,
+    name: string,
+    uri: string,
+    plugins: CorePlugin[],
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /** AddPluginV1, signed by `authority` (`null`: the payer): the owner for owner-managed plugins, else the update authority. */
+  addPlugin(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CorePlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /** UpdatePluginV1: new values for a plugin the asset has (no `authority`), e.g. `{ kind: "FreezeDelegate", frozen: true }`. */
+  updatePlugin(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CorePlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  removePlugin(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    kind: CorePluginKind,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  addCollectionPlugin(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CorePlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  updateCollectionPlugin(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CorePlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  removeCollectionPlugin(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    kind: CorePluginKind,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
   /** TransferV1, signed by the owner (or a delegate) as `authority` (`null`: the payer). */
   transferAsset(
     asset: AccountMeta,
@@ -521,6 +704,106 @@ export interface BubblegumProgram extends AccountMeta {
     sellerFeeBasisPoints: u16,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  /**
+   * CreateTreeConfigV2: a tree on mpl-account-compression (mcmt6…, allocated by the client and owned by it) with the
+   * mpl-noop log wrapper (mnoop…). `treeCreator` `null`: the payer.
+   */
+  createTreeV2(
+    treeConfig: AccountMeta,
+    merkleTree: AccountMeta,
+    payer: Mut<Signer>,
+    treeCreator: AccountMeta | null,
+    logWrapper: AccountMeta,
+    compressionProgram: AccountMeta,
+    systemProgram: SystemProgram,
+    maxDepth: u32,
+    maxBufferSize: u32,
+    isPublic: boolean,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /** MintV2 of a leaf, optionally into a Metaplex Core collection (whose update authority signs as `authority`). */
+  mintV2(
+    treeConfig: AccountMeta,
+    payer: Mut<Signer>,
+    treeDelegate: AccountMeta | null,
+    leafOwner: AccountMeta,
+    leafDelegate: AccountMeta | null,
+    merkleTree: AccountMeta,
+    logWrapper: AccountMeta,
+    compressionProgram: AccountMeta,
+    mplCoreProgram: AccountMeta,
+    systemProgram: SystemProgram,
+    metadata: CompressedMetadata,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  mintV2(
+    treeConfig: AccountMeta,
+    payer: Mut<Signer>,
+    treeDelegate: AccountMeta | null,
+    leafOwner: AccountMeta,
+    leafDelegate: AccountMeta | null,
+    merkleTree: AccountMeta,
+    logWrapper: AccountMeta,
+    compressionProgram: AccountMeta,
+    mplCoreProgram: AccountMeta,
+    systemProgram: SystemProgram,
+    metadata: CompressedMetadata,
+    collection: { collection: AccountMeta; authority: AccountMeta; cpiSigner: AccountMeta },
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /** TransferV2, signed by the owner or delegate as `authority` (`null`: the payer); `proof` is the leaf's Merkle proof. */
+  transferV2(
+    treeConfig: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    leafOwner: AccountMeta,
+    leafDelegate: AccountMeta | null,
+    newLeafOwner: AccountMeta,
+    merkleTree: AccountMeta,
+    coreCollection: AccountMeta | null,
+    logWrapper: AccountMeta,
+    compressionProgram: AccountMeta,
+    systemProgram: SystemProgram,
+    leaf: CompressedLeaf,
+    proof: RemainingAccounts | RemainingSlice,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  burnV2(
+    treeConfig: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    leafOwner: AccountMeta,
+    leafDelegate: AccountMeta | null,
+    merkleTree: AccountMeta,
+    coreCollection: AccountMeta | null,
+    mplCoreCpiSigner: AccountMeta | null,
+    logWrapper: AccountMeta,
+    compressionProgram: AccountMeta,
+    mplCoreProgram: AccountMeta,
+    systemProgram: SystemProgram,
+    leaf: CompressedLeaf,
+    proof: RemainingAccounts | RemainingSlice,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+}
+/** Bubblegum V2 leaf metadata (MetadataArgsV2): non-fungible, primary sale not happened, mutable unless `isMutable: false`. */
+export interface CompressedMetadata {
+  name: string;
+  symbol: string;
+  uri: string;
+  sellerFeeBasisPoints: u16;
+  creators?: { address: Pubkey; verified: boolean; share: u8 }[];
+  isMutable?: boolean;
+}
+/** The leaf a transfer or burn replaces, as an indexer (DAS getAssetProof / getAsset) reports it. */
+export interface CompressedLeaf {
+  root: Hash;
+  dataHash: Hash;
+  creatorHash: Hash;
+  assetDataHash?: Hash | null;
+  flags?: u8 | null;
+  nonce: u64;
+  index: u32;
 }
 
 /** The current slot and epoch (Clock sysvar). */
@@ -602,16 +885,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 +900,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.17.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",