@typesol/cli 0.14.0 → 0.16.0

package/dist/compiler/emit/statements.js

@@ -50,6 +50,8 @@ export class StatementEmitter extends CpiEmitter {
             return this.switchStatement(stmt);
         if (ts.isForStatement(stmt))
             return this.forLoop(stmt);
+        if (ts.isForOfStatement(stmt))
+            return this.forOf(stmt);
         if (ts.isWhileStatement(stmt))
             return this.loop(stmt.expression, stmt.statement, undefined);
         if (ts.isBreakStatement(stmt) || ts.isContinueStatement(stmt)) {
@@ -63,8 +65,8 @@ export class StatementEmitter extends CpiEmitter {
             this.line(ts.isBreakStatement(stmt) ? `break;` : `goto ${this.loops.at(-1)};`);
             return;
         }
-        if (ts.isDoStatement(stmt) || ts.isForOfStatement(stmt) || ts.isForInStatement(stmt))
-            this.fail(stmt, "only for (init; cond; step) and while loops are supported");
+        if (ts.isDoStatement(stmt) || ts.isForInStatement(stmt))
+            this.fail(stmt, "only for (init; cond; step), for (const x of list) and while loops are supported");
         this.fail(stmt, `${ts.SyntaxKind[stmt.kind]} is not supported in TypeSOL`);
     }
     returnStatement(stmt) {
@@ -77,6 +79,25 @@ export class StatementEmitter extends CpiEmitter {
             this.line(`return SUCCESS;`);
             return;
         }
+        if (returns.kind === "struct") {
+            if (!stmt.expression)
+                this.fail(stmt, `return a ${returns.name}`);
+            if (this.helper) {
+                // Write the struct through the caller's out pointer (a literal, a place or another helper's result).
+                this.writeAggregate({ lv: "(*ret)", type: returns, writable: true }, stmt.expression);
+                this.line(`return SUCCESS;`);
+                return;
+            }
+            // Return data: the struct's fixed layout, which the IDL describes field by field.
+            const t = this.tmp("ret");
+            this.line(`TSS_${returns.name} ${t};`);
+            this.writeAggregate({ lv: t, type: returns, writable: true }, stmt.expression);
+            this.line(`sol_set_return_data((const uint8_t *)&${t}, sizeof(${t}));`);
+            for (const l of this.epilogue())
+                this.line(l);
+            this.line(`return SUCCESS;`);
+            return;
+        }
         if (!stmt.expression)
             this.fail(stmt, `return a ${typeName(returns)}`);
         const v = this.expect(this.expr(stmt.expression, returns), returns, stmt.expression);
@@ -170,6 +191,65 @@ export class StatementEmitter extends CpiEmitter {
         });
         this.line(`}`);
     }
+    /**
+     * `for (const x of list)` over a Vec or FixedArray: an index loop that binds `x` as `const x = list.get(i)` would,
+     * so elements are values (scalars, strings) or references into the data (structs), with the same aliasing rules.
+     * As in JS, the length is read again before every step, so a body that pushes or pops sees the new length.
+     */
+    forOf(stmt) {
+        if (stmt.awaitModifier)
+            this.fail(stmt, "for await is not supported");
+        const list = stmt.initializer;
+        const d = ts.isVariableDeclarationList(list) && list.declarations.length === 1 ? list.declarations[0] : undefined;
+        if (!d || !(list.flags & ts.NodeFlags.Const) || !ts.isIdentifier(d.name) || d.type)
+            this.fail(stmt.initializer, "write for (const x of list): one const name, no type annotation");
+        if (this.isRemaining(stmt.expression))
+            this.fail(stmt.expression, "iterate remaining accounts with for (let i = 0n; i < rest.length; i++) and rest.get(i)");
+        // Synthetic `list.length` / `list.get(i)` nodes placed at the loop, so errors and checks point at the source.
+        const f = ts.factory;
+        const index = `__of${this.temp++}`;
+        const place = (n) => {
+            ts.setTextRange(n, stmt.expression);
+            n.parent = stmt;
+            return n;
+        };
+        const indexId = place(f.createIdentifier(index));
+        const length = place(f.createPropertyAccessExpression(stmt.expression, "length"));
+        const get = place(f.createCallExpression(place(f.createPropertyAccessExpression(stmt.expression, "get")), undefined, [indexId]));
+        // The element's declaration: the source's own name (so aliasing checks find its uses) bound to list.get(i).
+        const decl = f.createVariableDeclaration(d.name, undefined, undefined, get);
+        ts.setTextRange(decl, d);
+        decl.parent = list;
+        const declList = { ...list, flags: ts.NodeFlags.Const, declarations: [decl] };
+        const ci = this.tmp("of_i");
+        const label = this.tmp("ts_continue_");
+        this.line(`{`);
+        this.block(() => {
+            this.line(`uint64_t ${ci} = 0;`);
+            this.scopes.at(-1).set(index, { c: ci, type: U64, mutable: false });
+            this.line(`while (1) {`);
+            this.block(() => {
+                const n = this.expect(this.expr(length, U64), U64, stmt.expression);
+                this.line(`if (!(${ci} < ${n.c})) break;`);
+                this.variable(declList);
+                this.loops.push(label);
+                this.line(`{`);
+                this.block(() => this.body(stmt.statement));
+                this.line(`}`);
+                this.loops.pop();
+                this.line(`${label}:;`);
+                this.line(`${ci}++;`);
+            });
+            this.line(`}`);
+        });
+        this.line(`}`);
+    }
+    /** Whether `e` is the remaining accounts (or a const bound to them). */
+    isRemaining(e) {
+        if (ts.isCallExpression(e) && this.exportName(e.expression) === "remainingAccounts")
+            return true;
+        return ts.isIdentifier(e) && this.lookup(e.text)?.type.kind === "remaining";
+    }
     /**
      * `while (1) { cond; if (!cond) break; body; continue_label: step }`. The condition is lowered
      * inside the loop so its checked-arithmetic temporaries are recomputed every iteration.
@@ -204,6 +284,10 @@ export class StatementEmitter extends CpiEmitter {
         if (!(list.flags & (ts.NodeFlags.Const | ts.NodeFlags.Let)))
             this.fail(list, "use const or let, not var");
         for (const d of list.declarations) {
+            if (ts.isObjectBindingPattern(d.name) && d.initializer) {
+                this.destructure(list, d, d.name, d.initializer, topLevel);
+                continue;
+            }
             if (!ts.isIdentifier(d.name) || !d.initializer)
                 this.fail(d, "declare one plain name with an initializer");
             const name = d.name.text;
@@ -312,6 +396,39 @@ export class StatementEmitter extends CpiEmitter {
             this.scopes.at(-1).set(name, { c, type, mutable });
         }
     }
+    /**
+     * `const { a, b: c } = s`: one declaration per name, `const a = s.a`, in source order. The source must be a name or
+     * a field path (no calls), so reading it once per name reads the same thing JS reads once.
+     */
+    destructure(list, d, pattern, init, topLevel) {
+        if (d.type)
+            this.fail(d.type, "destructuring takes the types from the source; drop the annotation");
+        const plain = (e) => ts.isIdentifier(e) ||
+            (ts.isPropertyAccessExpression(e) && !e.questionDotToken && plain(e.expression)) ||
+            (ts.isParenthesizedExpression(e) && plain(e.expression));
+        if (!plain(init))
+            this.fail(init, "destructure a variable or a field (a.b.c); bind a call to a const first");
+        const f = ts.factory;
+        for (const el of pattern.elements) {
+            if (el.dotDotDotToken)
+                this.fail(el, "...rest is not supported in destructuring");
+            if (el.initializer)
+                this.fail(el, "default values are not supported in destructuring");
+            if (!ts.isIdentifier(el.name))
+                this.fail(el, "nested destructuring is not supported; destructure in two steps");
+            const prop = el.propertyName ?? el.name;
+            if (!ts.isIdentifier(prop))
+                this.fail(el, "use plain field names");
+            const access = f.createPropertyAccessExpression(init, prop.text);
+            ts.setTextRange(access, el);
+            access.parent = d;
+            // The element's own name node, so aliasing checks and the type checker find its uses.
+            const decl = f.createVariableDeclaration(el.name, undefined, undefined, access);
+            ts.setTextRange(decl, el);
+            decl.parent = list;
+            this.variable({ ...list, declarations: [decl] }, topLevel);
+        }
+    }
     expressionStatement(e, topLevel) {
         if (ts.isBinaryExpression(e)) {
             const op = e.operatorToken.kind;
@@ -332,6 +449,8 @@ export class StatementEmitter extends CpiEmitter {
             const base = compound[op];
             if (base !== undefined)
                 return this.assign(e.left, e.right, base);
+            if (op === ts.SyntaxKind.AsteriskAsteriskEqualsToken)
+                this.fail(e.operatorToken, "write x = x ** n instead of **=");
         }
         if ((ts.isPostfixUnaryExpression(e) || ts.isPrefixUnaryExpression(e)) &&
             (e.operator === ts.SyntaxKind.PlusPlusToken || e.operator === ts.SyntaxKind.MinusMinusToken)) {
@@ -384,8 +503,14 @@ export class StatementEmitter extends CpiEmitter {
         let raw = createsFirst ? this.call(valueNode, topLevel) : undefined;
         if (createsFirst && !raw)
             this.fail(valueNode, "this call does not produce a value");
+        // A helper's struct result is copied like any struct (the target first, as JS evaluates it first).
+        const structCall = isCall && ts.isIdentifier(valueNode.expression)
+            ? this.model.helpers.get(valueNode.expression.text)?.returns?.kind === "struct"
+            : false;
+        if (structCall && this.writesThroughVec(target) && this.helperTakesMutAccounts(valueNode))
+            this.fail(target, "the right side calls a helper that may change this Vec; store its result in a local first");
         // Whole arrays / structs: copy between identical layouts.
-        const targetRef = isCall ? undefined : this.ref(target);
+        const targetRef = isCall && !structCall ? undefined : this.ref(target);
         if (targetRef &&
             (targetRef.type.kind === "array" ||
                 targetRef.type.kind === "struct" ||
@@ -407,8 +532,9 @@ export class StatementEmitter extends CpiEmitter {
                 this.fail(valueNode, "this call does not produce a value");
         }
         let value = this.expect(raw ?? this.expr(valueNode, place.type), place.type, valueNode);
-        if (ts.isIdentifier(target))
-            value = this.ownedString(value); // a local keeps its own copy of account text
+        // A local, or a string field of a variable enum (a view), keeps its own copy of account text.
+        if (ts.isIdentifier(target) || (value.type.kind === "string" && this.peekKind(target) === "string"))
+            value = this.ownedString(value);
         this.line(place.write(value.c) + ";");
     }
     /** Whether a place goes through a Vec element (`v.get(i).x`, `v.get(i)`). */

package/dist/compiler/emit/storage.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { type FieldType, type ValueType } from "../model.js";
+import { type FieldType, type Helper, type ValueType } from "../model.js";
 import { type Value, type Ref } from "./shared.js";
 import { EmitterBase } from "./base.js";
 /**
@@ -7,6 +7,7 @@ import { EmitterBase } from "./base.js";
  * argument validation.
  */
 export declare abstract class StorageEmitter extends EmitterBase {
+    protected abstract callHelper(node: ts.CallExpression, h: Helper): Value | undefined;
     /** C lines rejecting malformed fixed-layout data at `lv`: bools, enums, option tags, string lengths, enum tags. */
     protected validation(lv: string, t: FieldType, pad: string, fail?: string): string[];
     /** The variants TypeScript has narrowed a data-enum expression to (e.g. inside `if (a.kind === "X")`). */

package/dist/compiler/emit/storage.js

@@ -73,12 +73,13 @@ export class StorageEmitter extends EmitterBase {
         return r?.type.kind === "dataEnum" ? r : undefined;
     }
     looksLikeDataEnum(node) {
-        const saved = { lines: this.lines.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
+        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
         try {
             return this.reporter.guard(() => this.ref(node))?.type.kind === "dataEnum";
         }
         finally {
             this.lines.length = saved.lines;
+            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
             this.temp = saved.temp;
             this.reporter.diagnostics.length = saved.diagnostics;
         }
@@ -144,7 +145,7 @@ export class StorageEmitter extends EmitterBase {
         // Loops around `at` that do not also contain the declaration run their earlier statements again later.
         let loop;
         for (let n = at.parent; n && n !== decl.parent; n = n.parent)
-            if ((ts.isForStatement(n) || ts.isWhileStatement(n) || ts.isDoStatement(n)) && !(decl.pos >= n.pos && decl.end <= n.end))
+            if ((ts.isForStatement(n) || ts.isForOfStatement(n) || ts.isWhileStatement(n) || ts.isDoStatement(n)) && !(decl.pos >= n.pos && decl.end <= n.end))
                 loop = n;
         let found = false;
         const scope = decl.parent.parent.parent; // VariableDeclaration -> List -> Statement -> enclosing block
@@ -207,13 +208,14 @@ export class StorageEmitter extends EmitterBase {
             return this.looksLikeStructPlace(node.expression);
         if (ts.isConditionalExpression(node))
             return this.looksLikeStructPlace(node.whenTrue) && this.looksLikeStructPlace(node.whenFalse);
-        const saved = { lines: this.lines.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
+        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
         try {
             const r = this.reporter.guard(() => this.ref(node));
             return r?.type.kind === "struct";
         }
         finally {
             this.lines.length = saved.lines;
+            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
             this.temp = saved.temp;
             this.reporter.diagnostics.length = saved.diagnostics;
         }
@@ -241,6 +243,14 @@ export class StorageEmitter extends EmitterBase {
         if (ts.isParenthesizedExpression(node))
             return this.ref(node.expression);
         this.noOptionalChain(node);
+        // A helper's struct result: a local of the caller's, read and copied like any struct.
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            const h = this.model.helpers.get(node.expression.text);
+            if (h?.returns?.kind === "struct" && !this.lookup(node.expression.text)) {
+                const v = this.callHelper(node, h);
+                return { lv: `(*${v.c})`, type: { kind: "struct", name: h.returns.name }, writable: true };
+            }
+        }
         if (ts.isIdentifier(node)) {
             const l = this.lookup(node.text);
             if (l && l.type.kind === "array")
@@ -284,7 +294,9 @@ export class StorageEmitter extends EmitterBase {
                     const vi = e.variants.findIndex((v) => v.name === n);
                     const fields = e.variants[vi]?.fields ?? [];
                     const at = fields.findIndex((x) => x.name === field);
-                    const offset = fields.slice(0, Math.max(at, 0)).reduce((sum, x) => sum + this.fieldBytes(x.type), 0);
+                    // In the C payload a string is a TS_Str view (16 bytes); everything else has its stored size.
+                    const cBytes = (t) => (t.kind === "string" ? 16 : this.fieldBytes(t));
+                    const offset = fields.slice(0, Math.max(at, 0)).reduce((sum, x) => sum + cBytes(x.type), 0);
                     return { vi, name: n, f: fields[at], offset };
                 });
                 if (located.some((l) => !l.f))
@@ -412,6 +424,8 @@ export class StorageEmitter extends EmitterBase {
                 return { c: `(&${r.lv})`, type: r.type };
             case "fstring":
                 return { c: `ts_fstr_view((const uint8_t *)&${r.lv}, ${r.type.cap})`, type: STRING };
+            case "string":
+                return { c: r.lv, type: STRING }; // a variable enum's text: already a view
             case "enum":
                 return { c: r.lv, type: r.type };
             case "option":
@@ -439,6 +453,7 @@ export class StorageEmitter extends EmitterBase {
                 return `${r.lv} = *(${c})`;
             case "fstring":
                 return `TS_TRY(ts_fstr_set((uint8_t *)&${r.lv}, ${r.type.cap}, ${c}))`;
+            case "string":
             case "enum":
             case "option":
                 return `${r.lv} = ${c}`;
@@ -449,7 +464,7 @@ export class StorageEmitter extends EmitterBase {
     storageValueType(t) {
         if (isScalar(t))
             return t;
-        if (t.kind === "fstring")
+        if (t.kind === "fstring" || t.kind === "string")
             return STRING;
         if (t.kind === "option" && t.inner.kind !== "struct")
             return t;
@@ -510,8 +525,9 @@ export class StorageEmitter extends EmitterBase {
                 const f = variant.fields.find((x) => x.name === name);
                 const sub = { lv: `${tmp}.v.${variant.name}.${f.name}`, type: f.type, writable: true };
                 const vt = this.storageValueType(f.type);
+                // A string kept in a variable enum holds its own copy of account text (the account may change later).
                 if (vt)
-                    this.line(this.writeStorage(sub, this.expect(this.expr(ex, vt), vt, ex).c) + ";");
+                    this.line(this.writeStorage(sub, this.ownedString(this.expect(this.expr(ex, vt), vt, ex)).c) + ";");
                 else
                     this.writeAggregate(sub, ex);
             }
@@ -570,12 +586,13 @@ export class StorageEmitter extends EmitterBase {
     }
     /** The kind of storage an expression names (struct, array, dataEnum…), without emitting code or failing. */
     peekKind(node) {
-        const saved = { lines: this.lines.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
+        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
         try {
             return this.reporter.guard(() => this.ref(node))?.type.kind;
         }
         finally {
             this.lines.length = saved.lines;
+            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
             this.temp = saved.temp;
             this.reporter.diagnostics.length = saved.diagnostics;
         }

package/dist/compiler/idl.js

@@ -153,28 +153,42 @@ export function buildIdl(model, address, version = "0.1.0") {
                 },
             })),
             ...[...model.enums.values()].map((e) => ({ name: e.name, type: { kind: "enum", variants: e.variants.map((v) => ({ name: v })) } })),
+            // A variable enum (it holds strings) only exists in Borsh: no fixed account-data form to describe.
             ...[...model.dataEnums.values()].flatMap((e) => [
                 {
                     name: e.name,
                     ...docsOf(e.node),
                     type: {
                         kind: "enum",
-                        variants: e.variants.map((v) => v.fields.length ? { name: v.name, fields: v.fields.map((f) => ({ name: snakeCase(f.name), type: idlType(f.type) })) } : { name: v.name }),
-                    },
-                },
-                {
-                    name: fixedEnumName(e.name),
-                    docs: [
-                        `TypeSOL ${e.name} in account data: \`tag\` is the variant index, \`payload\` the variant's fields (Borsh layout) padded to the largest variant.`,
-                    ],
-                    type: {
-                        kind: "struct",
-                        fields: [
-                            { name: "tag", type: "u8" },
-                            { name: "payload", type: { array: ["u8", e.payload] } },
-                        ],
+                        variants: e.variants.map((v) => v.fields.length
+                            ? {
+                                name: v.name,
+                                // A nested variable enum only exists in Borsh; fixed fields keep the fixed forms the bytes use.
+                                fields: v.fields.map((f) => ({
+                                    name: snakeCase(f.name),
+                                    type: f.type.kind === "dataEnum" && model.dataEnums.get(f.type.name)?.variable ? { defined: { name: f.type.name } } : idlType(f.type),
+                                })),
+                            }
+                            : { name: v.name }),
                     },
                 },
+                ...(e.variable
+                    ? []
+                    : [
+                        {
+                            name: fixedEnumName(e.name),
+                            docs: [
+                                `TypeSOL ${e.name} in account data: \`tag\` is the variant index, \`payload\` the variant's fields (Borsh layout) padded to the largest variant.`,
+                            ],
+                            type: {
+                                kind: "struct",
+                                fields: [
+                                    { name: "tag", type: "u8" },
+                                    { name: "payload", type: { array: ["u8", e.payload] } },
+                                ],
+                            },
+                        },
+                    ]),
             ]),
             ...[...model.options.values()].map((inner) => ({
                 name: fixedOptionName(inner),

package/dist/compiler/model.d.ts

@@ -278,7 +278,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). */
@@ -294,11 +298,15 @@ 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 non-exported function (or any function of an imported file): values and accounts in; void, a scalar or a struct out. */
 export interface Helper {
     name: string;
     params: HelperParam[];
-    returns: ScalarType | undefined;
+    /** A struct result is written through an out pointer (`TSS_<name> *ret`) that the caller provides. */
+    returns: ScalarType | {
+        kind: "struct";
+        name: string;
+    } | undefined;
     node: ts.FunctionDeclaration;
     /** The declaring file's `typesol` imports (local name -> export name). */
     imports: Map<string, string>;
@@ -322,6 +330,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 }`. */

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/idlpublish.js

@@ -62,17 +62,51 @@ export async function publishIdl(chain, opts) {
             seeds: [getAddressEncoder().encode(opts.program)],
         }))[0]
         : undefined;
-    await writeMetadata(client, {
-        payer: opts.payer,
-        authority,
-        program: opts.program,
-        ...(programData ? { programData } : {}),
-        seed: "idl",
-        format: Format.Json,
-        ...packed,
-    });
+    try {
+        await writeMetadata(client, {
+            payer: opts.payer,
+            authority,
+            program: opts.program,
+            ...(programData ? { programData } : {}),
+            seed: "idl",
+            format: Format.Json,
+            ...packed,
+        });
+    }
+    catch (e) {
+        throw new Error(planFailure(e));
+    }
     return metadataAddress(opts.program, canonical ? null : authority.address);
 }
+/**
+ * The transaction planner reports a failed write as "The provided transaction plan failed to execute" and keeps the
+ * reason inside: name the first failed transaction's own error instead.
+ */
+function planFailure(e) {
+    const seen = new Set();
+    const messages = [];
+    let logs = [];
+    const walk = (v, depth) => {
+        if (!v || typeof v !== "object" || seen.has(v) || depth > 8)
+            return;
+        seen.add(v);
+        const o = v;
+        if (Array.isArray(o.logs) && !logs.length)
+            logs = o.logs.map(String);
+        if (v instanceof Error && v.message && !/transaction plan failed to execute/.test(v.message))
+            messages.push(v.message);
+        for (const k of ["transactionPlanResult", "plans", "error", "cause", "context"]) {
+            const c = o[k];
+            if (Array.isArray(c))
+                c.forEach((x) => walk(x, depth + 1));
+            else
+                walk(c, depth + 1);
+        }
+    };
+    walk(e, 0);
+    const tail = logs.length ? `\n  ${logs.slice(-6).join("\n  ")}` : "";
+    return messages.length ? `IDL write failed: ${messages[0]}${tail}` : e instanceof Error ? e.message : String(e);
+}
 export async function metadataAddress(program, authority) {
     return (await findMetadataPda({ program, authority, seed: "idl" }))[0];
 }

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);
+}