@typesol/cli 0.15.0 → 0.17.0

package/dist/compiler/model.d.ts

@@ -110,9 +110,11 @@ export type FieldType = ScalarType | {
     name: string;
 }
 /** `Vec<T>`: Borsh u32 length + elements. Only as the last field of an account struct. */
+/** `Vec<T>` (last field, grows the account) or, with `cap`, `FixedVec<T, N>`: a u32 length and room for N elements. */
  | {
     kind: "vec";
     elem: FieldType;
+    cap?: number;
 };
 export interface StructField {
     name: string;
@@ -136,6 +138,11 @@ export interface StructDef {
     accountDiscriminator: number[];
     eventDiscriminator: number[];
     node: ts.InterfaceDeclaration;
+    /**
+     * How account data stores it: "fixed" (every field at a fixed offset, the default) or "borsh" (`@layout borsh`:
+     * Anchor's bytes, where strings, Vecs and Options take only what they hold).
+     */
+    layout: "fixed" | "borsh";
 }
 export type TokenProgramKind = "token" | "token2022" | "tokenInterface";
 export type ParamKind = {
@@ -278,7 +285,11 @@ export interface Instruction {
     args: ArgParam[];
     /** Fixed bytes of the arguments; strings add their length on top. */
     minArgsSize: number;
-    returns: ScalarType | undefined;
+    /** Sent as return data: a scalar in Borsh, or a fixed-size struct in its fixed layout (as the IDL describes it). */
+    returns: ScalarType | {
+        kind: "struct";
+        name: string;
+    } | undefined;
     /** account name -> seeds, recorded when the body creates or verifies a PDA with describable seeds. */
     pdas: Map<string, IdlSeed[]>;
     /** account name -> the program its PDA is derived under, when not this program (e.g. associated token accounts). */
@@ -287,6 +298,14 @@ export interface Instruction {
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
 }
+/** A helper with type parameters, before it is instantiated. */
+export interface GenericHelper {
+    name: string;
+    display: string;
+    node: HelperNode;
+    typeParams: string[];
+    imports: Map<string, string>;
+}
 export interface HelperParam {
     name: string;
     /** `{ kind: "account" }` for account parameters (then `account` says which kind). */
@@ -294,12 +313,28 @@ export interface HelperParam {
     account?: ParamKind;
     node: ts.ParameterDeclaration;
 }
-/** A non-exported function (or any function of an imported file): values and accounts in, scalar or void out. */
+/** A function written as `function f(…)`, `const f = (…) => …` or `const f = function (…) {…}`. */
+export type HelperNode = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/**
+ * A non-exported function (or any function of an imported file), or an arrow function declared with const at the top
+ * level or inside a function (capturing nothing): values and accounts in; void, a scalar or a struct out.
+ */
 export interface Helper {
+    /** The C name (fn_<name>): the function's name, `outer__local` for a local arrow, `name__u64` for an instance. */
     name: string;
+    /** The name in messages: `local`, `max<u64>`. */
+    display: string;
     params: HelperParam[];
-    returns: ScalarType | undefined;
-    node: ts.FunctionDeclaration;
+    /** A struct result is written through an out pointer (`TSS_<name> *ret`) that the caller provides. */
+    returns: ScalarType | {
+        kind: "struct";
+        name: string;
+    } | undefined;
+    node: HelperNode;
+    /** The body; an arrow's expression body is one return (or expression) statement. */
+    statements: readonly ts.Statement[];
+    /** A generic helper's instance: type parameter -> the type it stands for. */
+    typeArgs?: Map<string, ScalarType>;
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
 }
@@ -322,6 +357,11 @@ export interface DataEnumDef {
     }[];
     /** Largest variant size: the fixed payload in account data. */
     payload: number;
+    /**
+     * A variant holds a `string` (directly or in a nested enum): such an enum is Borsh in instruction arguments and
+     * events and a local value otherwise, never account data or part of a fixed layout. Its C payload holds TS_Str views.
+     */
+    variable?: boolean;
     node: ts.TypeAliasDeclaration;
 }
 /** A unit-variant enum: `export enum Status { Open, Closed }`. */
@@ -339,6 +379,10 @@ export interface ProgramModel {
     structs: Map<string, StructDef>;
     instructions: Instruction[];
     helpers: Map<string, Helper>;
+    /** Generic helpers by name: instantiated (into `helpers`) for the types each call uses. */
+    generics: Map<string, GenericHelper>;
+    /** Declaration (function, or the const of an arrow) -> helper or generic name, for calls to local arrows. */
+    helperDecls: Map<ts.Node, string>;
     errors: ErrorDef[];
     /** Enum name -> member name -> error */
     errorEnums: Map<string, Map<string, ErrorDef>>;
@@ -361,6 +405,10 @@ export interface ProgramModel {
     argStructs: Set<string>;
     /** FixedString capacities in use, for C typedefs and IDL types. */
     fstrings: Set<number>;
+    /** FixedVec<T, N> types in use (IDL name -> type), for IDL types. */
+    fixedVecs: Map<string, FieldType & {
+        kind: "vec";
+    }>;
 }
 export declare function isWritable(k: ParamKind): boolean;
 export declare function typeName(t: ValueType | FieldType): string;
@@ -373,3 +421,7 @@ export declare function optionKey(t: ScalarType | {
     name: string;
 }): string;
 export declare function scalarKey(t: ScalarType): string;
+/** The IDL type name of a FixedVec<T, N>: `FixedVec<N>_<T>`. */
+export declare function fixedVecName(t: FieldType & {
+    kind: "vec";
+}): string;

package/dist/compiler/model.js

@@ -56,7 +56,7 @@ export function typeName(t) {
         case "enumRef":
             return t.name;
         case "vec":
-            return `Vec<${typeName(t.elem)}>`;
+            return t.cap === undefined ? `Vec<${typeName(t.elem)}>` : `FixedVec<${typeName(t.elem)}, ${t.cap}>`;
         case "vecArg":
             return `Vec<${typeName(t.elem)}>`;
         case "arrayArg":
@@ -92,7 +92,7 @@ export function sameType(a, b) {
         case "option":
             return sameType(a.inner, b.inner);
         case "vec":
-            return sameType(a.elem, b.elem);
+            return a.cap === b.cap && sameType(a.elem, b.elem);
         case "vecArg":
             return sameType(a.elem, b.elem);
         case "arrayArg":
@@ -120,3 +120,9 @@ export function optionKey(t) {
 export function scalarKey(t) {
     return t.kind === "int" ? t.name : t.kind === "enum" ? `e_${t.name}` : t.kind === "pubkey" && t.hash ? "hash" : t.kind;
 }
+/** The IDL type name of a FixedVec<T, N>: `FixedVec<N>_<T>`. */
+export function fixedVecName(t) {
+    return `FixedVec${t.cap}_${typeName(t.elem)
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/_+$/, "")}`;
+}

package/dist/compiler/toolchain.d.ts

@@ -14,6 +14,8 @@ export interface Toolchain {
 /** Locate the Solana C SDK that ships with the Agave CLI's platform-tools. */
 export declare function findToolchain(sbpf?: Sbpf): Toolchain;
 /** Compile generated C to an SBF shared object (same flags as the SDK's sbf.mk for the chosen SBPF version). */
+/** The SBF stack frame of one function. */
+export declare const STACK_FRAME = 4096;
 export declare function buildSharedObject(cFile: string, outSo: string, sbpf?: Sbpf, tc?: Toolchain): void;
 /** The clang version string, for build manifests. */
 export declare function toolchainVersion(tc?: Toolchain): string;

package/dist/compiler/toolchain.js

@@ -51,6 +51,8 @@ export function findToolchain(sbpf = "v0") {
     };
 }
 /** Compile generated C to an SBF shared object (same flags as the SDK's sbf.mk for the chosen SBPF version). */
+/** The SBF stack frame of one function. */
+export const STACK_FRAME = 4096;
 export function buildSharedObject(cFile, outSo, sbpf = "v0", tc = findToolchain(sbpf)) {
     const obj = outSo.replace(/\.so$/, ".o");
     const cflags = [
@@ -58,6 +60,9 @@ export function buildSharedObject(cFile, outSo, sbpf = "v0", tc = findToolchain(
         "-Wno-parentheses-equality",
         // Generated checks may be always true/false (`a === a`, `enumByte >= 256` for a 256-variant enum); that is not an error.
         "-Wno-tautological-compare",
+        // SBPF v0 gives every function a fixed 4 KiB stack frame; past it the program corrupts memory instead of failing.
+        // v1 and v2 grow frames dynamically, so the limit does not apply there.
+        ...(sbpf === "v0" ? [`-Wframe-larger-than=${STACK_FRAME}`] : []),
         "-O2",
         "-fno-builtin",
         // One section per function and constant, so the linker's --gc-sections can drop what nothing reaches.
@@ -70,7 +75,12 @@ export function buildSharedObject(cFile, outSo, sbpf = "v0", tc = findToolchain(
         ...(sbpf === "v0" ? [] : [`-mcpu=${sbpf}`]),
     ];
     const incs = tc.includes.flatMap((i, n) => (n < 2 ? ["-isystem", i] : ["-I", i]));
-    run(tc.clang, [...cflags, ...incs, "-o", obj, "-c", cFile]);
+    try {
+        run(tc.clang, [...cflags, ...incs, "-o", obj, "-c", cFile]);
+    }
+    catch (e) {
+        throw stackError(e.message) ?? e;
+    }
     run(tc.lld, [
         "-z",
         "notext",
@@ -99,6 +109,22 @@ export function buildSharedObject(cFile, outSo, sbpf = "v0", tc = findToolchain(
 export function toolchainVersion(tc = findToolchain()) {
     return execFileSync(tc.clang, ["--version"], { encoding: "utf8" }).split("\n")[0].trim();
 }
+/** clang's frame-size errors, in the program's terms: which instruction or helper, how much, what to do. */
+function stackError(message) {
+    const over = [...message.matchAll(/stack frame size \((\d+)\) exceeds limit \((\d+)\) in '(\w+)'/g)];
+    if (!over.length)
+        return undefined;
+    // clang inlines helpers into their callers, so an instruction's frame includes theirs.
+    const what = (fn) => fn.startsWith("ix_") ? `instruction ${fn.slice(3)} (with the helpers inlined into it)` : fn.startsWith("fn_") ? `helper ${fn.slice(3)}()` : fn;
+    // Anything else clang reported in the same run stays in the message.
+    const rest = message
+        .split("\n")
+        .filter((l) => / error: /.test(l) && !/-Wframe-larger-than/.test(l))
+        .join("\n");
+    return new Error(over.map((m) => `${what(m[3])} needs ${m[1]} bytes of stack; SBPF v0 gives each function ${m[2]}`).join("\n") +
+        "\nKeep large structs and arrays in account data: bind them with const (a reference) instead of a typed local copy, or split the work into helpers." +
+        (rest ? `\n${rest}` : ""));
+}
 function run(cmd, args) {
     try {
         execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });

package/dist/onchain.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A deployed program read straight from a cluster, for `typesol verify --address`: its ELF bytes and who can still
+ * change them. Handles the three loaders a program can live under:
+ *
+ * - upgradeable (loader v3, what `solana program deploy` uses): the program account points at a ProgramData account
+ *   holding the deploy slot, the upgrade authority (none once frozen) and then the ELF;
+ * - loader v4: one account holding the slot, the authority, the status and then the ELF;
+ * - the old non-upgradeable loader (v2): the account data is the ELF itself.
+ */
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+export declare const LOADER_V2 = "BPFLoader2111111111111111111111111111111111";
+export declare const LOADER_V3 = "BPFLoaderUpgradeab1e11111111111111111111111";
+export declare const LOADER_V4 = "LoaderV411111111111111111111111111111111111";
+export interface Deployed {
+    loader: "v2" | "v3" | "v4";
+    /** The ELF as stored (loader v3 keeps it zero-padded to the account's allocation). */
+    elf: Buffer;
+    /** Who can upgrade or close it; null when the program is immutable. */
+    authority: string | null;
+    /** The slot of the last deploy or upgrade (v3, v4). */
+    slot?: bigint;
+    /** Where the bytes live (the ProgramData account for v3). */
+    dataAccount: string;
+}
+type AccountRpc = Pick<Rpc<SolanaRpcApi>, "getAccountInfo">;
+/** The deployed program at `programId`, or an error that says why there is none. */
+export declare function fetchDeployed(rpc: AccountRpc, programId: string): Promise<Deployed>;
+/** JSON with object keys sorted, so two IDLs compare by content and not by key order. */
+export declare function canonicalJson(v: unknown): string;
+export {};

package/dist/onchain.js

@@ -0,0 +1,53 @@
+import { getAddressDecoder } from "@solana/kit";
+export const LOADER_V2 = "BPFLoader2111111111111111111111111111111111";
+export const LOADER_V3 = "BPFLoaderUpgradeab1e11111111111111111111111";
+export const LOADER_V4 = "LoaderV411111111111111111111111111111111111";
+async function account(rpc, address) {
+    const { value } = await rpc.getAccountInfo(address, { encoding: "base64", commitment: "confirmed" }).send();
+    if (!value)
+        return null;
+    return { owner: value.owner, data: Buffer.from(value.data[0], "base64") };
+}
+const key = (data, offset) => getAddressDecoder().decode(data.subarray(offset, offset + 32));
+/** The deployed program at `programId`, or an error that says why there is none. */
+export async function fetchDeployed(rpc, programId) {
+    const program = await account(rpc, programId);
+    if (!program)
+        throw new Error(`no account at ${programId} on this cluster`);
+    if (program.owner === LOADER_V2)
+        return { loader: "v2", elf: program.data, authority: null, dataAccount: programId };
+    if (program.owner === LOADER_V4) {
+        // u64 slot, authority (or next version), u64 status (0 retracted, 1 deployed, 2 finalized), then the ELF.
+        if (program.data.length < 48)
+            throw new Error(`${programId} is not a loader-v4 program`);
+        const status = program.data.readBigUInt64LE(40);
+        if (status === 0n)
+            throw new Error(`${programId} is retracted (loader v4): it has no executable code`);
+        return {
+            loader: "v4",
+            elf: program.data.subarray(48),
+            authority: status === 2n ? null : key(program.data, 8),
+            slot: program.data.readBigUInt64LE(0),
+            dataAccount: programId,
+        };
+    }
+    if (program.owner !== LOADER_V3)
+        throw new Error(`${programId} is not a program (owner ${program.owner})`);
+    // Program account: u32 state = 2, ProgramData address.
+    if (program.data.length < 36 || program.data.readUInt32LE(0) !== 2)
+        throw new Error(`${programId} is an upgradeable-loader account but not a program`);
+    const dataAccount = key(program.data, 4);
+    const pd = await account(rpc, dataAccount);
+    // ProgramData: u32 state = 3, u64 slot, Option<Pubkey> authority (1 + 32 bytes), then the ELF.
+    if (!pd || pd.owner !== LOADER_V3 || pd.data.length < 45 || pd.data.readUInt32LE(0) !== 3)
+        throw new Error(`${programId} has no program data (closed or never deployed)`);
+    return { loader: "v3", elf: pd.data.subarray(45), authority: pd.data[12] ? key(pd.data, 13) : null, slot: pd.data.readBigUInt64LE(4), dataAccount };
+}
+/** JSON with object keys sorted, so two IDLs compare by content and not by key order. */
+export function canonicalJson(v) {
+    return JSON.stringify(v, (_k, x) => x && typeof x === "object" && !Array.isArray(x)
+        ? Object.fromEntries(Object.keys(x)
+            .sort()
+            .map((k) => [k, x[k]]))
+        : x);
+}

package/dist/portgen.d.ts

@@ -0,0 +1,87 @@
+type IdlType = string | {
+    vec?: IdlType;
+    option?: IdlType;
+    coption?: IdlType;
+    array?: [IdlType, number | unknown];
+    defined?: string | {
+        name: string;
+        generics?: unknown[];
+    };
+};
+interface IdlField {
+    name: string;
+    type: IdlType;
+    docs?: string[];
+}
+interface IdlTypeDef {
+    name: string;
+    docs?: string[];
+    type: {
+        kind: string;
+        fields?: (IdlField | IdlType)[];
+        variants?: {
+            name: string;
+            fields?: (IdlField | IdlType)[];
+        }[];
+    };
+    generics?: unknown[];
+}
+interface IdlAccountItem {
+    name: string;
+    writable?: boolean;
+    signer?: boolean;
+    optional?: boolean;
+    address?: string;
+    docs?: string[];
+    pda?: {
+        seeds: {
+            kind: string;
+            value?: number[];
+            path?: string;
+        }[];
+        program?: unknown;
+    };
+    relations?: string[];
+    accounts?: IdlAccountItem[];
+}
+interface IdlInstruction {
+    name: string;
+    docs?: string[];
+    discriminator: number[];
+    accounts: IdlAccountItem[];
+    args: IdlField[];
+    returns?: IdlType;
+}
+export interface PortIdl {
+    address?: string;
+    metadata?: {
+        name?: string;
+    };
+    instructions: IdlInstruction[];
+    accounts?: {
+        name: string;
+        discriminator: number[];
+    }[];
+    events?: {
+        name: string;
+        discriminator: number[];
+    }[];
+    errors?: {
+        code: number;
+        name: string;
+        msg?: string;
+    }[];
+    types?: IdlTypeDef[];
+    constants?: {
+        name: string;
+        type: IdlType;
+        value: string;
+    }[];
+}
+export interface PortResult {
+    source: string;
+    /** What the skeleton cannot carry over as is, and where Anchor clients would see a different layout. */
+    notes: string[];
+}
+export declare function generatePort(idl: PortIdl): PortResult;
+export {};