@typesol/cli 0.21.0 → 0.23.0

package/dist/svmrpc.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests as they run against a
+ * cluster: `sendInstructions`, `simulate`, `views`, `accounts.<Name>.fetch*` and `watch`, `resolve`, `eventsOf` and
+ * `watchEvents`. Only the methods those helpers call are answered.
+ *
+ *   const { rpc, rpcSubscriptions } = svmConnection(svm);
+ *   await counter.sendInstructions({ rpc, rpcSubscriptions }, alice, [await counter.initialize({ authority: alice })]);
+ *   await counter.accounts.Counter.fetch(rpc, address);
+ *
+ * Transactions run as they are sent (confirmed at once). LiteSVM cannot list accounts, so `getProgramAccounts` scans
+ * the accounts transactions sent through this connection named, plus those passed to `track`.
+ */
+import { type Address, type Rpc, type RpcSubscriptions, type SolanaRpcApi, type SolanaRpcSubscriptionsApi } from "@solana/kit";
+import { type LiteSVM, type TransactionMetadata } from "litesvm";
+export interface SvmConnection {
+    rpc: Rpc<SolanaRpcApi>;
+    rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi>;
+    /** Every transaction sent through `rpc` that succeeded, in order. */
+    transactions: {
+        signature: string;
+        meta: TransactionMetadata;
+    }[];
+    /** Add accounts for `getProgramAccounts` to scan (accounts the transactions named are scanned already). */
+    track(...addresses: Address[]): void;
+}
+export declare function svmConnection(svm: LiteSVM): SvmConnection;

package/dist/svmrpc.js

@@ -0,0 +1,150 @@
+/**
+ * A kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests as they run against a
+ * cluster: `sendInstructions`, `simulate`, `views`, `accounts.<Name>.fetch*` and `watch`, `resolve`, `eventsOf` and
+ * `watchEvents`. Only the methods those helpers call are answered.
+ *
+ *   const { rpc, rpcSubscriptions } = svmConnection(svm);
+ *   await counter.sendInstructions({ rpc, rpcSubscriptions }, alice, [await counter.initialize({ authority: alice })]);
+ *   await counter.accounts.Counter.fetch(rpc, address);
+ *
+ * Transactions run as they are sent (confirmed at once). LiteSVM cannot list accounts, so `getProgramAccounts` scans
+ * the accounts transactions sent through this connection named, plus those passed to `track`.
+ */
+import { getAddressDecoder, getBase58Decoder, getBase58Encoder, getBase64Decoder, getBase64Encoder, getCompiledTransactionMessageDecoder, getTransactionDecoder, } from "@solana/kit";
+import { FailedTransactionMetadata } from "litesvm";
+const b64 = (bytes) => getBase64Decoder().decode(bytes);
+const reply = (value) => ({ send: async () => value });
+export function svmConnection(svm) {
+    const transactions = [];
+    const known = new Set();
+    const decode = (wire) => {
+        const tx = getTransactionDecoder().decode(getBase64Encoder().encode(wire));
+        return { tx, keys: getCompiledTransactionMessageDecoder().decode(tx.messageBytes).staticAccounts };
+    };
+    const encoded = (a) => {
+        const acct = svm.getAccount(a);
+        if (!acct.exists)
+            return null;
+        return {
+            data: [b64(acct.data), "base64"],
+            executable: acct.executable,
+            lamports: acct.lamports,
+            owner: acct.programAddress,
+            space: BigInt(acct.data.length),
+            rentEpoch: 0n,
+        };
+    };
+    const rpc = {
+        getLatestBlockhash: () => reply({ context: { slot: 0n }, value: { blockhash: svm.latestBlockhash(), lastValidBlockHeight: 1000000n } }),
+        getEpochInfo: () => reply({ absoluteSlot: 0n, blockHeight: 0n, epoch: 0n, slotIndex: 0n, slotsInEpoch: 432000n, transactionCount: null }),
+        getSignatureStatuses: (sigs) => reply({
+            context: { slot: 0n },
+            value: sigs.map((s) => transactions.some((t) => t.signature === s)
+                ? { confirmationStatus: "confirmed", confirmations: null, err: null, slot: 0n, status: { Ok: null } }
+                : null),
+        }),
+        getMinimumBalanceForRentExemption: (space) => reply(svm.minimumBalanceForRentExemption(space)),
+        getBalance: (a) => reply({ context: { slot: 0n }, value: svm.getBalance(a) ?? 0n }),
+        sendTransaction: (wire) => ({
+            send: async () => {
+                const { tx, keys } = decode(wire);
+                const res = svm.sendTransaction(tx);
+                svm.expireBlockhash();
+                if (res instanceof FailedTransactionMetadata)
+                    throw new Error(`transaction failed: ${String(res.err())}\n${res.meta().logs().join("\n")}`);
+                for (const k of keys)
+                    known.add(k);
+                const signature = getBase58Decoder().decode(res.signature());
+                transactions.push({ signature, meta: res });
+                return signature;
+            },
+        }),
+        simulateTransaction: (wire, config = {}) => ({
+            send: async () => {
+                // Simulations are usually unsigned (sigVerify: false): turn LiteSVM's check off for this one only.
+                const inner = svm.inner;
+                const restore = config.sigVerify === false && inner?.getSigverify?.() === true;
+                if (restore)
+                    svm.withSigverify(false);
+                let res;
+                try {
+                    res = svm.simulateTransaction(decode(wire).tx);
+                }
+                finally {
+                    if (restore)
+                        svm.withSigverify(true);
+                }
+                if (res instanceof FailedTransactionMetadata)
+                    return {
+                        context: { slot: 0n },
+                        value: { err: String(res.err()), logs: res.meta().logs(), unitsConsumed: res.meta().computeUnitsConsumed(), returnData: null },
+                    };
+                const meta = res.meta();
+                const ret = meta.returnData();
+                return {
+                    context: { slot: 0n },
+                    value: {
+                        err: null,
+                        logs: meta.logs(),
+                        unitsConsumed: meta.computeUnitsConsumed(),
+                        returnData: ret.data().length ? { programId: getAddressDecoder().decode(ret.programId()), data: [b64(ret.data()), "base64"] } : null,
+                    },
+                };
+            },
+        }),
+        getAccountInfo: (a) => reply({ context: { slot: 0n }, value: encoded(a) }),
+        getMultipleAccounts: (addresses) => reply({ context: { slot: 0n }, value: addresses.map(encoded) }),
+        getProgramAccounts: (program, config = {}) => reply([...known]
+            .map((a) => ({ pubkey: a, account: encoded(a) }))
+            .filter(({ account }) => account && account.owner === program)
+            .filter(({ account }) => {
+            const data = getBase64Encoder().encode(account.data[0]);
+            return (config.filters ?? []).every(({ memcmp, dataSize }) => {
+                if (dataSize !== undefined)
+                    return BigInt(data.length) === BigInt(dataSize);
+                if (!memcmp)
+                    return true;
+                const want = getBase58Encoder().encode(memcmp.bytes);
+                return want.every((b, i) => data[Number(memcmp.offset) + i] === b);
+            });
+        })),
+        // The json shape: log messages, and inner instructions with base58 data (what `eventsOf` reads).
+        getTransaction: (signature) => {
+            const t = transactions.find((x) => x.signature === signature);
+            return reply(t
+                ? {
+                    slot: 0n,
+                    blockTime: null,
+                    meta: {
+                        err: null,
+                        logMessages: t.meta.logs(),
+                        computeUnitsConsumed: t.meta.computeUnitsConsumed(),
+                        innerInstructions: t.meta
+                            .innerInstructions()
+                            .map((group, index) => ({ index, instructions: group.map((i) => ({ data: getBase58Decoder().decode(i.instruction().data()) })) })),
+                    },
+                }
+                : null);
+        },
+    };
+    /** Notifications that end when the subscriber aborts. */
+    const stream = (items) => ({
+        subscribe: async ({ abortSignal }) => (async function* () {
+            for (const item of items())
+                yield item;
+            await new Promise((resolve) => abortSignal.addEventListener("abort", resolve, { once: true }));
+        })(),
+    });
+    const rpcSubscriptions = {
+        signatureNotifications: () => stream(() => [{ context: { slot: 0n }, value: { err: null } }]),
+        slotNotifications: () => stream(() => []),
+        logsNotifications: () => stream(() => transactions.map((t) => ({ context: { slot: 0n }, value: { signature: t.signature, logs: t.meta.logs(), err: null } }))),
+        accountNotifications: (a) => stream(() => [{ context: { slot: 0n }, value: encoded(a) ?? { data: ["", "base64"], lamports: 0n } }]),
+    };
+    return {
+        rpc: rpc,
+        rpcSubscriptions: rpcSubscriptions,
+        transactions,
+        track: (...addresses) => addresses.forEach((a) => known.add(a)),
+    };
+}

package/dist/testing.d.ts

@@ -19,6 +19,8 @@
 import anchor, { type Idl } from "@anchor-lang/core";
 import { type Address, type Instruction, type KeyPairSigner } from "@solana/kit";
 import { FailedTransactionMetadata, LiteSVM, TransactionMetadata } from "litesvm";
+import { type SvmConnection, svmConnection } from "./svmrpc.js";
+export { type SvmConnection, svmConnection };
 declare const BorshCoder: typeof anchor.BorshCoder;
 type BorshCoder = InstanceType<typeof BorshCoder>;
 export type Result = TransactionMetadata | FailedTransactionMetadata;
@@ -58,9 +60,10 @@ export interface TestProgram {
     returned<T = unknown>(instruction: string, res: Result): T;
     /** Lamports of any account (0 when it does not exist). */
     balance(address: Address): bigint;
+    /** A kit RPC and subscriptions pair over this LiteSVM, for the generated client (`svmConnection`). */
+    connection: SvmConnection;
 }
 /** Build `program` of the project around `from` (a file URL such as import.meta.url, or a directory) and load it. */
 export declare function testProgram(program: string, from: string | URL): Promise<TestProgram>;
 /** The same helpers for a program already loaded into `svm` at `programId` with this IDL. */
 export declare function programHarness(svm: LiteSVM, programId: Address, idl: Idl): TestProgram;
-export {};

package/dist/testing.js

@@ -22,7 +22,9 @@ import { FailedTransactionMetadata, LiteSVM } from "litesvm";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { svmConnection } from "./svmrpc.js";
 import { buildWorkspace, findWorkspace } from "./workspace.js";
+export { svmConnection };
 // @anchor-lang/core is CommonJS: Node 22 cannot import its classes by name from an installed ES module.
 const { BN, BorshCoder } = anchor;
 const BIG = new Set(["u64", "i64", "u128", "i128"]);
@@ -332,6 +334,7 @@ export function programHarness(svm, programId, idl) {
         balance(address) {
             return svm.getBalance(address) ?? 0n;
         },
+        connection: svmConnection(svm),
     };
     return harness;
 }

package/docs/client.md

@@ -48,7 +48,7 @@ for await (const { signature, event } of ledgerbook.watchEvents(rpcSubscriptions
 await ledgerbook.approveMany({ approver: signer, book }, { indices: [0n, 1n] }, [{ address: extra, role: AccountRole.WRITABLE }]);
 
 // has_one accounts that do not sign, read from the account that names them (Anchor resolves `relations` the same way)
-const accounts = await ledgerbook.resolve.someInstruction(rpc, { book }); // fills in what book's Pubkey fields name
+const accounts = await ledgerbook.resolve.someInstruction(rpc, { book }, { signer }); // signers, and what book's fields name
 
 // Events of a fetched transaction (getTransaction, json): log events and emitCpi events from inner instructions
 ledgerbook.eventsOf(await rpc.getTransaction(signature, { maxSupportedTransactionVersion: 0 }).send());
@@ -64,9 +64,9 @@ Kit's own transaction functions work with the instructions as well; `sendInstruc
 | `<program>.<instruction>(accounts, args)` | Builds the `Instruction`. Accounts with a fixed address and PDAs whose seeds are constants, arguments or other accounts' keys are optional and filled in; pass one to override. An optional account passed as `null` is left out (sent as the program id, the convention TypeSOL and Anchor share); left undefined, it is filled in like any other. |
 | `<program>.<instruction>(accounts, args, remaining?)` | The same, with remaining accounts appended in order (kit `AccountMeta`s). |
 | `<program>.accounts.<Name>` | `decode(bytes)`, `encode(value)`, `fetch(rpc, address)`, `fetchMaybe(rpc, address)`, `fetchMultiple(rpc, addresses)`, `fetchAll(rpc, filters?)` (getProgramAccounts by discriminator, plus `{ offset, bytes }` filters), `watch(rpcSubscriptions, address, { abortSignal })`, `discriminator`. `decode` checks the discriminator. |
-| `<program>.pdas.<account>(seeds)` | The PDA (address and bump) for each account an instruction derives. |
+| `<program>.pdas.<account>(seeds)` | The PDA (address and bump) for each account an instruction derives, also one seeded from its own fields (from the field values). |
 | `<program>.returns.<instruction>(bytes)` | Decodes return data. |
-| `<program>.resolve.<instruction>(rpc, accounts, args?)` | Fills in what needs the chain: `has_one` accounts that do not sign (read from the account that names them) and PDAs seeded from another account's fields (`seeds = [b"vault", book.owner]`: the account is read, then the PDA derived). Given accounts are kept. |
+| `<program>.resolve.<instruction>(rpc, accounts, args?, { signer? })` | Fills in what needs the chain or the wallet: signer accounts left out (`options.signer`, the default signer, like Anchor's provider wallet), `has_one` accounts that do not sign (read from the account that names them), and PDAs seeded from another account's fields, scalars, strings or bytes (`seeds = [b"vault", book.owner]`: the account is read, then the PDA derived). Given accounts are kept. |
 | `<program>.views.<instruction>(rpc, feePayer, accounts, args)` | Simulates an instruction that returns a value and decodes it (throws with the logs if it fails). |
 | `<program>.sendInstructions(connection, feePayer, instructions)`, `simulate(rpc, feePayer, instructions)` | One transaction sent and confirmed (kit's sendAndConfirm), or simulated without signatures (error, logs, units, this program's return data). |
 | `<program>.errors`, `errorCode(e)`, `isError(e, name)` | The program's errors (6000+), and for TypeSOL programs also every Anchor framework error (`AnchorError` and the constraints raise them) and TypeSOL's runtime errors. |
@@ -89,12 +89,14 @@ Anchor IDLs are refused with a hint to convert them (`anchor idl convert`).
 
 - **Errors and events are matched by code and discriminator, not by program.** A program this one calls can raise the
   same error code, and `parseEvents` reads every `Program data:` line that decodes as one of this program's events.
-- **Not filled in automatically** (pass them): `has_one` accounts that sign (they have to sign), PDAs seeded from an
-  account's own fields or from fields inside an argument, PDAs seeded from non-scalar fields (strings, structs), and PDAs
-  whose program comes from an argument. `typesol client` prints a note for each. `has_one` accounts that do not sign and
-  PDAs seeded from another account's scalar fields are filled in by `resolve` (it reads the chain).
-- **Left out of a client generated from an Anchor IDL**, with a note: generic types and anything using them, and
-  zero-copy (`bytemuck`) accounts.
-- **Not done yet**: a LiteSVM loader for tests (use `svm.addProgramFromFile(ledgerbook.address, soPath)`, or
-  `typesol/testing`). `watchEvents` reads log events; with `rpc` it also fetches each transaction in which the program
-  invoked itself and reads its `emitCpi` events (log subscriptions do not carry inner instructions).
+- **Not filled in automatically** (pass them): PDAs seeded from struct fields (Anchor cannot seed with them either),
+  PDAs whose program is another account's field, and a PDA seeded from its own fields (derive it with its `pdas`
+  helper from the values). `typesol client` prints a note for each.
+- **Anchor IDLs**: zero-copy (`bytemuck`) accounts decode and encode at their `#[repr(C)]` offsets as the program sees
+  them on SBF (padding included; `packed` and `align` honored; 128-bit integers align to 8). Generic types become one
+  type per use with concrete arguments (`Pair<u64, 2>` is `PairU64N2`). Left out, with a note: zero-copy types with
+  Rust's own layout (`repr(Rust)`) or holding a non-zero-copy type, and the generic definitions themselves.
+- **In tests**: `svmConnection(svm)` from `typesol/testing` answers the client's RPC calls from LiteSVM, and
+  `testProgram(...)` has it as `t.connection` ([test-your-program.md](test-your-program.md)).
+- `watchEvents` reads log events; with `rpc` it also fetches each transaction in which the program invoked itself and
+  reads its `emitCpi` events (log subscriptions do not carry inner instructions).

package/docs/language.md

@@ -21,12 +21,12 @@ The full reference. For a tour, start with the [README](../README.md).
 | Destructuring | `const { owner, pos: p } = acct` (or `let` for scalars to change) from a name or a field path — one declaration per name, read like `acct.owner`: scalars are copies, nested structs are references. No rest, defaults or nesting |
 | Struct values | `const p: Point = { x, y }` (or a copy of another Point) — a local struct; fields can be updated, store it with `acct.home = p` |
 | Pubkey constants | `const ADMIN = pubkey("4Nd1…")` (checked at compile time) or inline `pubkey("…")`; usable as seeds |
-| Events | `emit<Deposited>({ owner: owner.key, amount })` — Anchor-format `Program data:` logs, listed under `events` in the IDL; event structs may hold `string` and `Option` |
+| Events | `emit<Deposited>({ owner: owner.key, amount })` — Anchor-format `Program data:` logs, listed under `events` in the IDL; event structs may hold `string`, `Option`, `FixedVec<T, N>` (its fixed layout, as in account data) and `Vec<T>` (Borsh: from a Vec argument or a list in account data) |
 | Enums | `export enum Status { Pending, Approved }` — unit variants stored as the Borsh u8 index; `Status.Approved`, `===` |
 | Options | `best: Option<u64>` (or `u64 \| null`) — `null`, `=== null`, TypeScript narrowing; `===` between options or with a value follows JS (null equals null, empty never equals a value); empty use aborts (5108); `acct?.field` on an optional account and `x.home?.field` on an `Option<struct>` give an Option (empty when the account was left out / the option is empty), `a ?? b` takes b only when a is empty (b runs only then; the result is an Option when b can be null), `x!` is the value or aborts with 5108; `${opt}` prints the value or `null`. Borsh `option` in arguments/events, fixed `{ is_some, value }` in account data |
-| Vecs | `entries: Vec<Entry>` as the last account field — `get`, `set`, `push(v, payer)`, `pop()`, `clear()`, `.length`; the account is resized (realloc) and rent topped up by `payer`; `Vec<u64>` arguments are read-only views; `Vec<string>` arguments (Anchor's `Vec<String>`) are views of the instruction data, each checked as UTF-8 on entry (102), and go back out as Borsh through `invoke`; `pop()` of a Vec of structs works as a statement |
+| Vecs | `entries: Vec<Entry>` in account data, any number of them, declared anywhere: they are stored after the fixed-size fields in the order declared (so every other field keeps its offset; the IDL lists that order), and a push, pop or clear moves the Vecs after it (a reference into one of those cannot be used across it). In a `@layout borsh` struct a Vec is the last field (Anchor's order) — `get`, `set`, `push(v, payer)`, `pop()`, `clear()`, `.length`; the account is resized (realloc) and rent topped up by `payer`; `Vec<u64>` arguments are read-only views; `Vec<string>` arguments (Anchor's `Vec<String>`) are views of the instruction data, each checked as UTF-8 on entry (102), and go back out as Borsh through `invoke`; `pop()` of a Vec of structs works as a statement |
 | Anchor's account bytes | `/** @layout borsh */` on an account struct stores it as Anchor does (Borsh: a `FixedString<N>` is a String, a `FixedVec<T, N>` a Vec, an `Option` one byte when empty, and the fields after them move), so a TypeSOL program can take over accounts an Anchor program wrote and the IDL lists Anchor's own types. The instruction unpacks it into the usual fixed layout when it starts (bad bytes fail with 3003) and packs it back when it returns (3004 when the account is too small for the new value), so everything else works on it unchanged. Programs invoked from the body (CPIs) see the account's bytes as they were when the instruction started. Costs more compute than the fixed layout (the whole account is read and written each time; see the benchmarks); nested structs and list elements must be fixed-size (FixedString elements allowed). The same struct is Borsh as a whole instruction argument (checked like Borsh deserialization, UTF-8 included), as return data and as an event; as those (not as account data) it may also hold `string` fields and data enums carrying strings, Anchor's `String` and enums in argument structs (account data takes data enums without strings); not inside list or enum arguments, `Zeroed<T>`, `loadAccount` or a growable `Vec<T>` |
-| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed). Account data and returned structs only: arguments use `Vec<T>` |
+| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed). In account data, returned structs and events; as an argument (`ids: FixedVec<u64, 8>`) it is a Borsh Vec of at most N elements, read like a `Vec` argument (more fail with 102) |
 | Struct arguments | `order: Order`, `ids: FixedArray<u8, 4>`, `orders: Vec<Order>` — fixed layouts, Borsh-identical, validated on entry (bools, enums, option tags, string lengths, enum tags; 102) and read-only |
 | Remaining accounts | `remainingAccounts()` — `.length`, `.get(i)` → `key`, `owner`, `lamports` (writes check writability), `isSigner`, `isWritable`; `loadAccount<T>` / `loadAccountMut<T>` give checked struct views; pass them to `invoke`, one at a time or spread: `...remainingAccounts()` (each with the flags it was passed with), `...readonly(rest)` / `...writable(rest)` (all with that role), `rest.slice(a, b)` for part of them; a CPI lists at most 32 accounts (5113) |
 | Struct literals | `book.entries.push({ who: who.key, amount, status: Status.Pending, note }, who)` — every field required |
@@ -44,8 +44,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Loops | `for (let i = 0n; i < n; i++)`, `while`, `do … while`, `for (const x of list)` over a `Vec` or `FixedArray` (each `x` is what `list.get(i)` gives: a value, or a reference into account data for structs; the length is read again every step, as in JS), `break`, `continue` — bounded by the compute budget. Remaining accounts are iterated by index |
 | Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return `void`, a scalar or a fixed-size struct (`function at(x: u64, y: u64): Point { return { x, y }; }`: the caller gets its own copy, to bind, store with `acct.home = at(…)` / `arr.set(i, at(…))` or read as `at(…).x`); no recursion. A helper that takes a struct account as `Mut<T>` can grow its Vec (`push(value, payer)`: the account's size at instruction entry is passed along) |
 | Arrow functions and closures | `const fee = (x: u64): u64 => x / 100n` (or `const f = function (…) {…}`) at the top level or inside a function. One that reads or writes the enclosing function's variables (a closure: `let total = 0n; const add = (v: u64): void => { total += v; }`) is expanded where it is called: its names mean what they meant where it was declared, struct parameters are references, `return` leaves the closure; it cannot call itself. One that captures nothing becomes a helper. Parameter types may be left out on closures (taken from the arguments) |
-| Functions as arguments | a helper may take a function parameter (`function applyTwice(f: (x: u64) => u64, v: u64): u64`): it is compiled once per named function passed (a helper or a local function that captures nothing). Closures and arrow literals cannot be passed to helpers (a closure only runs where it is declared) |
-| List callbacks | on a `Vec`, `FixedArray`, `FixedVec` or `Vec` argument: `forEach`, `some`, `every`, `find` (an Option of the element; scalar elements), `findIndex` (i64, -1 when absent), `reduce(fn, initial)`, `includes(value)`, `indexOf(value)` (i64). The arrow written at the call is expanded into a loop (elements as `list.get(i)` gives them, structs by reference) and may read and write the function's variables |
+| Functions as arguments | a helper may take a function parameter (`function applyTwice(f: (x: u64) => u64, v: u64): u64`): it is compiled once per named function passed (a helper or a local function that captures nothing). An arrow written at the call works too (`applyTwice((x) => x * 3n, v)`: its types come from the parameter) when it reads none of the function's variables. Given a closure (one that reads them), the helper is expanded where it is called instead, like a closure, so it runs where the closure can; such a helper takes values, not accounts, and has no type parameters |
+| List callbacks | on a `Vec`, `FixedArray`, `FixedVec` or `Vec` argument: `forEach`, `some`, `every`, `find` (an Option of the element; scalar elements), `findIndex` (i64, -1 when absent), `reduce(fn, initial)`, `includes(value)`, `indexOf(value)` (i64), `map` and `filter`. The arrow written at the call is expanded into a loop (elements as `list.get(i)` gives them, structs by reference) and may read and write the function's variables. A `map` / `filter` chain used right away (`xs.filter(f).map(g).reduce(h, 0n)`, `.length`, `for … of`) is one loop that stores nothing; callbacks after a filter get the index among the elements it let through. Stored (`const ys = xs.filter(f)`), it is a FixedVec on the stack as big as the list it starts from; from a `Vec`, give the size: `const ys: FixedVec<u64, 16> = …` (at most 2 KiB; one element more aborts with 5104). `map` gives integers, booleans, Pubkeys or enums |
 | Generic helpers | `function max<T extends bigint>(a: T, b: T): T` — compiled once per set of types it is called with (`max(a, b)` with u64 arguments, or `max<u128>(x, 1n)` when only literals tell); a type parameter stands for an integer, boolean, Pubkey, enum or fixed-size struct (`pick<Point>(…)`, or from struct arguments; a struct `T` is copied like any struct value). Each instance is checked like any helper; one that is never called is not compiled (TypeScript still type-checks it). Arithmetic on `T` is a `bigint` to TypeScript: `return (a + b) as T` (`as` names a type the value already has; it never converts) |
 | Evaluation order | operands and arguments are read left to right, as in JS, even when a later one changes account data (`v.length + v.pop()`) |
 | `++` `--` `+=` `-=` `*=` `/=` `%=` `&=` `\|=` `^=` `<<=` `>>=` | all checked |
@@ -154,12 +154,12 @@ an integer literal, an argument, `acct.key` or a scalar field of an account, the
 
 ## Not supported yet
 
-Growable `Vec`s anywhere but the last account field (use `FixedVec<T, N>`), FixedVec in arguments and events outside
-`@layout borsh` structs, growing an account by more than 10 KiB in one instruction (Solana's limit: realloc again in
+A struct argument holding a FixedVec (use `@layout borsh` for the struct, or a FixedVec argument of its own), growing an account by more than 10 KiB in one instruction (Solana's limit: realloc again in
 the next instruction), `?.` on anything but optional accounts and Option<struct> fields, `!` on anything but an Option
 or an optional account, Core's external plugin adapters (oracles, app data, lifecycle hooks: use `invoke`), closures
-stored or returned (they are called or passed to list methods), arrow literals and closures as helper arguments (pass a
-named function), `map` / `filter` (they would build a new list), floating point (by design).
+stored or returned (they are called, passed to list methods or given to helpers), a helper with type parameters or
+account parameters given a closure, a stored `map` result of structs or
+strings, floating point (by design).
 They are rejected at compile time rather than half-supported.
 
 `Init.create` handles a PDA address someone pre-funded: it tops up rent, then allocates and assigns instead of

package/docs/test-your-program.md

@@ -44,9 +44,12 @@ it("counts", async () => {
 | `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.connection` | `{ rpc, rpcSubscriptions }` answered by this LiteSVM, for the generated client: `counter.sendInstructions(t.connection, alice, [ix])`, `counter.accounts.Counter.fetch(t.connection.rpc, address)`, views, `resolve`, `watch` and `watchEvents` |
 
 `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.
+program you loaded yourself, and `svmConnection(svm)` the RPC pair alone (for any LiteSVM, e.g. one with an Anchor
+program loaded). Transactions sent through it run at once; `getProgramAccounts` (`fetchAll`) sees the accounts those
+transactions named, plus any you `track(...)`.
 
 The module needs `litesvm` and `@anchor-lang/core`, which `typesol init` adds to `devDependencies`.

package/lib/typesol.d.ts

@@ -50,6 +50,14 @@ export interface ListMethods<T> {
   includes(value: T): boolean;
   /** The index of the first element equal to `value`, or -1. */
   indexOf(value: T): i64;
+  /**
+   * The elements `fn` maps them to (integers, booleans, Pubkeys or enums). Use it right away (another list method,
+   * `.length`, `for … of`: one loop, nothing stored) or store it (`const ys = xs.map(…)`: a FixedVec on the stack, as
+   * big as `xs`; from a `Vec`, annotate it: `const ys: FixedVec<u64, 16> = …`).
+   */
+  map<U>(fn: (x: T, index: u64) => U): FixedVec<U, never>;
+  /** The elements `fn` holds for, used or stored like `map`'s; callbacks after it get the index among those. */
+  filter(fn: (x: T, index: u64) => boolean): FixedVec<T, never>;
 }
 
 export interface FixedArray<T, N extends number> extends ListMethods<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",

package/runtime/typesol_rt.h

@@ -104,6 +104,25 @@ static inline __attribute__((always_inline)) void ts_memcpy(void *dst, const voi
   for (; n; n--) *d++ = *s++;
 }
 
+/* Copy that may overlap (a growable Vec's followers moving when it grows or shrinks): forward or backward as needed. */
+static inline void ts_memmove(void *dst, const void *src, uint64_t n) {
+  uint8_t *d = (uint8_t *)dst;
+  const uint8_t *s = (const uint8_t *)src;
+  if (d == s || n == 0) return;
+  if (d < s) {
+    ts_memcpy(d, s, n); /* forward: each 8-byte load happens before the store that could overlap it */
+    return;
+  }
+  d += n;
+  s += n;
+  for (; n >= 8; n -= 8) {
+    d -= 8;
+    s -= 8;
+    ts_st64(d, ts_ld64(s));
+  }
+  while (n--) *--d = *--s;
+}
+
 static inline __attribute__((always_inline)) void ts_memzero(void *dst, uint64_t n) {
   uint8_t *d = (uint8_t *)dst;
   for (; n >= 8; n -= 8, d += 8) ts_st64(d, 0);