Add BCH helper functions and non-spendable library imports

[lightswarm124]

This PR adds BCH function support on top of current next by introducing contract-local helper functions and non-spendable imported helper libraries. It treats OP_DEFINE / OP_INVOKE as first-class compiler outputs, keeps spend surfaces explicit, and adds the debug/runtime metadata needed to make helper execution reviewable.

Main changes:

• Adds public and internal function support inside contract.
• Adds first-class library containers for imported helper-only code.
• Supports contract -> library and transitive library -> library imports.
• Canonicalizes shared transitive libraries by resolved file identity to avoid duplicate shared-leaf codegen.
• Adds helper-aware debug metadata and SDK attribution for nested helper logs and failures.
• Rejects unsafe helper patterns:
  • recursion and mutual recursion
  • signature-check builtins in helpers
  • contract-constructor capture in helpers
  • imported contract files
  • public functions inside library

Why this matters:

• Enables reusable BCH helper functions both locally and across imported helper libraries.
• Keeps imported helper files non-spendable by construction.
• Makes nested helper execution inspectable enough for maintainers and downstream teams to audit.

Examples included:

Local internal helpers:

• examples/helper-functions.cash
• examples/helper-functions.ts

Imported helper libraries:

• examples/imported-helper-functions.cash
• examples/math-helpers.cash
• examples/parity-helpers.cash
• examples/imported-helper-functions.ts

Testing-suite helper example:

• examples/testing-suite/contracts/internal_functions.cash
• examples/testing-suite/test/internal_functions.test.ts

Docs for review:

• docs/proposals/bch-functions-team-review.md
• docs/proposals/functions-vs-next-review.md
• docs/proposals/functions-implementation-spec.md
• docs/proposals/functions-security-and-release-review.md

[rkalis]

Hey @lightswarm124, thank you for the PR. We have functions on the timeline for version 0.14.0, which we'll start working on after the upcoming 0.13.0 release (targeted for May 15th), which will mainly include loops.

We briefly looked at some of the changes, and I wonder whether the new examples compile, since the syntax changes don't look reflected in the grammar files. Did you manage to run any of these examples yet?

In any case, we'll start looking into this PR (and functions in general) after that upcoming 0.13.0 release in May.

[lightswarm124]

Hey @rkalis, I modified the grammar a bit to better support internal helper functions, adding in "public" and "internal" visibility tags to the functions. Also defined "library" for importing helper functions from external files - currently, only "contract" is allowed to have functions you can spend from.

Tests should work once the grammar has been updated

[vercel]

@lightswarm124 is attempting to deploy a commit to the Kalis Software Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cashscript	Ready	Preview, Comment	Jun 2, 2026 8:27am

[rkalis]

Hey Jerry, thanks for the update.

We looked deeper into the code / structure this week. Overall this serves as a good reference of implementing internal functions, libraries, and importing. However, there's still some issues, such as the visibility modifiers kind of living outside of the main compiler, and the lack of "returnable" functions.

If you wanted to further improve the PR, I noticed that there's some small type issues (I believe in the tests) which could be fixed, the PR could be rebased on top of the latest master, and getting the visibility modifiers reflected in the grammar + "proper" compiler process, rather than the current "bypass" / stripping method would be very helpful.

We have a list of smaller issues to still work on (following on the 0.13 release), before we are able to fully pick up functions. You can track the other issues in the v0.13.1 milestone and track functions + other bigger items in the 0.14.0 milestone.