Multi-return functions, global constants, and op-cost-aware function inlining

[mr-zwets]

Multi-return functions, global constants, and op-cost-aware function inlining

This PR builds on the user-defined function support released in v0.14.0-next.1, extending the language with multi-value returns and global constants, and adding a set of compiler optimisations focused on executed op-cost (targeting op-bound contracts like heavy math/ZK workloads).

Language features

• Multi-return global functions — functions can declare returns (T, U, ...) and return a, b, ..., destructured at the call site with N-ary tuple assignment (int a, int b = f(...)). Composes with imports; no new keywords.
• Destructuring into existing variables — tuple targets may be bare identifiers to reassign already-declared variables (a, b = f(x)), enabling in-place updates of loop-carried state.
• Top-level global constants — int constant P = <expr>; at file top level, including in imported files. Initializers are folded at compile time and inlined at every use site, so uses are plain literal pushes (no invoke or loop-stepping overhead).
• unused modifier on variables and parameters — exempts intentionally unreferenced bindings from the unused-variable check (e.g. padding-byte parameters that raise the compute budget).

Compiler optimisations

• Function inlining (on by default) — global functions are spliced at call sites instead of shared via OP_DEFINE/OP_INVOKE when cheaper by exact byte accounting. Single-use functions always inline; recursive functions never do. Debug info (source maps, logs, require messages) is spliced per call site, so debugging keeps working.
• Loop-aware exclusion — the VM charges base cost for opcodes even in untaken branches, so functions called inside loops stay OP_DEFINE'd (except tiny bodies, which are strictly cheaper inlined).
• New optimizeFor: 'size' | 'opcost' objective (default 'opcost', CLI -O) — the single switch for size-vs-op-cost trade-offs: under 'size' repeated in-body constants are hoisted to locals; under 'opcost' small bodies (≤ 6 bytes) are always inlined.
• Cheaper calling convention — arguments are staged right-to-left (first parameter on top), so a typical call with in-order variable arguments costs zero staging instructions. Measured ~2.9–5M op-cost saved on call-dense groth16 builds.
• Altstack lowering for function-exit cleanup — past a break-even point, exit cleanup parks return values on the altstack and drops dead locals in OP_2DROP pairs (~1 op per 2 drops instead of 3 per drop).
• Faster peephole optimiser — matches patterns directly against the script array instead of regex-scanning re-stringified ASM (was quadratic in script size). Output is byte-for-byte identical. Also adds the commutative OP_SWAP OP_MUL rule.
• Legacy-optimiser cross-check gating — skipped automatically above 10k unoptimised ops, or explicitly via disableOptimisationCrossCheck.

New compiler options

optimizeFor, disableInlining, disableOptimisationCrossCheck (all documented on CompilerOptions).

Notes for reviewers

• Bytecode for contracts using global functions changes by design (inlining is on by default); tests that assert on the OP_DEFINE/OP_INVOKE shape now pass disableInlining: true.
• Runtime behaviour is verified via MockNetworkProvider for multi-return ordering, destructuring reassignment in loops, and all inlining shapes (single-use, multi-use, recursion, multi-return).

[vercel]

@mr-zwets is attempting to deploy a commit to the Kalis Software Team on Vercel.

A member of the Team first needs to authorize it.

[mr-zwets]

Follow-up on the Compiler optimisations list

the relative importance and the opcost-vs-bytesize axis was missing. The reversed calling convention is the standout, so it
gets its own section; the rest split into ones that change the output and ones that are
compile-time only.

One framing up front: these split across two axes. Some save locking bytecode directly; others
save opcost. For opcost-constrained contracts the two are linked — the unlocking carries
opcost-sized padding, so saved opcost turns into fewer unlocking bytes.

Reversed calling convention

A convention choice, not an algorithm: compile function bodies expecting the first parameter on
top and stage arguments right-to-left. For a call passing variables in declaration order on final
use, each OP_ROLL then peels from the top (depths 0,1,2,…, the depth-0 roll elided) instead of
digging to the bottom every time (depths arity-1), so in-order arguments need no reordering. It's
neutral for ordinary 1–3 arg calls and slightly worse for a reused argument like f(a, a); the win
is real only for call-dense, high-arity bodies (unrolled crypto), where it's material.

Two reasons it belongs in the compiler rather than as caller-side arg reversal (which gets the same
effect): the natural, readable order should be the free one; and a hand-reversal isn't safe once an
argument recurs or is nested, since reversed emission breaks the "roll on last use" assumption. That
safety can't be decided per-argument (it depends on whether a name recurs elsewhere in the tree), so
the commit adds a small occurrence guard that only rolls a name used once — and it fails closed
(demoting a roll to a pick is always safe; only the reverse would corrupt the stack).

It also removes an inconsistency: constructor arguments are baked in reverse declaration order
(generateContractBytecodeScript) and contract-function arguments are seeded the same way, so both
already put the first parameter on top. The old last-parameter-on-top convention made user-defined
functions the lone exception; this aligns them, and lets the body seed through the same
visitParameter path the constructor and spend params use.

Debugging note: because arguments sit in reverse declaration order, at the low level (e.g. BitAuth
IDE) they appear on the stack reversed relative to the signature — first parameter on top, last
deepest. This already holds for constructor and contract-function arguments; the change just makes
user-function calls match.

Output optimisations (size / opcost)

Roughly biggest to smallest for opcost-constrained contracts:

• optimizeFor (constant hoisting) — a modest but real bytecode-size win, but only under
  -O size; the default 'opcost' objective doesn't run it. A general size feature, not an
  opcost one.
• Function inlining — small on both axes for typical code (most helpers are single-use or
  loop-resident); mostly about dropping the OP_INVOKE round-trip on non-loop calls rather than
  bytes.
• Altstack lowering for function-exit cleanup — small, break-even gated; only matters on
  cleanup-heavy exits.
• Loop-aware exclusion — really a guardrail for inlining rather than a saving of its own: it
  stops inlining from duplicating a body into a loop. Prevents a regression rather than beating
  the baseline.

Compile-time only (output unchanged)

These don't change the emitted script at all — they make the compiler itself viable on large
contracts:

• Faster peephole optimiser — output is byte-for-byte identical; fixes a quadratic scan that
  hurts large contracts. The new OP_SWAP OP_MUL rule is marginal.
• Legacy-optimiser cross-check gating — no output change; lets large contracts compile without
  the quadratic cross-check.

So the group is mostly an opcost package rather than a bytesize one, with the calling convention
as the standout and constant-hoisting as the one direct size win (under -O size). Happy to
share the measured A/B numbers behind any of these if useful.