Since Ledger v2.2, two versions of the Numscript interpreter are available: the original, built directly into our Ledger service, and a new portable and embeddable interpreter that can run independently or enhance other ledgering systems.
The original interpreter is enabled by default but is no longer evolving, while the new version will receive ongoing updates and must be manually enabled.
To enable the new interpreter:
ledger.experimental-featurestruedefault: falseboolEnables general experimental features in the ledger by setting the EXPERIMENTAL_FEATURES environment variable on the deployment.
ledger.experimental-numscripttruedefault: falseboolEnables the experimental Numscript interpreter in the ledger by setting the EXPERIMENTAL_NUMSCRIPT_INTERPRETER environment variable.
The new interpreter supports additional language features not available in the original, including oneof, account interpolation, asset colors, and more. See the Numscript reference for the full list and how to enable each one.
Selecting the interpreter per transaction#
Each transaction picks its interpreter through the runtime field on the create-transaction request body:
machine(default) — the original interpreter built into the Ledger.experimental-interpreter— the new interpreter. Required for any experimental feature.
Using runtime: experimental-interpreter also requires the Ledger to run with the new interpreter enabled (the ledger.experimental-features and ledger.experimental-numscript settings above), and each experimental feature must additionally be enabled via its own #![feature(...)] flag.
Experimental feature availability#
Which experimental features you can use depends on the Numscript interpreter version bundled in your Ledger release. The reference pages reflect this automatically — a feature only appears once your selected Stack/Ledger version bundles an interpreter recent enough to support it.
| Feature | Flag | Interpreter | Available from |
|---|---|---|---|
| OneOf | experimental-oneof | 0.0.15 | Ledger 2.3 / Stack v3.1 |
| Account interpolation | experimental-account-interpolation | 0.0.15 | Ledger 2.3 / Stack v3.1 |
| Mid-script function calls | experimental-mid-script-function-call | 0.0.15 | Ledger 2.3 / Stack v3.1 |
| Overdraft function | experimental-overdraft-function | 0.0.15 | Ledger 2.3 / Stack v3.1 |
| get_asset | experimental-get-asset-function | 0.0.16 | Ledger 2.3 / Stack v3.1 |
| get_amount | experimental-get-amount-function | 0.0.16 | Ledger 2.3 / Stack v3.1 |
| Asset colors | experimental-asset-colors | 0.0.17 | Ledger 2.3 / Stack v3.1 |
For the callable functions specifically (with live per-function availability against your selection), see Functions.
The Numscript playground uses the new interpreter. Experimental features can be toggled individually in the playground's feature flags selector.