Candle 1
Candle 1 defines the first generation of the Candle ecosystem.
It brings together the following components:
- CandleVM 1.x — the bytecode virtual machine.
- CASM 1 - the low-level programming language.
- CandleStd 1.x — standard-library functionality.
- CandleSys 1.x — system capabilities provided through a native plugin.
Components
Recommended Rust Compiler Version
For the Candle 1 ecosystem generation, the recommended Rust compiler version (rustc) for compiling plugins is 1.99.1.
This version is used as the reference compiler version for CandleVM to ensure compatibility between plugins and CandleVM.
Using a different rustc version is possible, but compatibility with CandleVM is not guaranteed. Plugins compiled with other compiler versions may encounter compatibility issues when loaded by the runtime.
Versioning Policy
The Candle ecosystem uses different versioning rules depending on the role of each component. These rules ensure bytecode compatibility across releases while allowing system and standard-library functionality to evolve independently.
CandleVM and CandleC
CandleVM and CandleC prioritize compatibility across all releases within the same ecosystem generation.
Their versions follow the MAJOR.MINOR.PATCH format:
- MAJOR — Identifies the ecosystem generation. Changes that break compatibility with previous releases of the same generation must be reserved for a new major version.
- MINOR — Introduces internal refactoring, significant optimizations, and other improvements that preserve the existing public bytecode contract.
- PATCH — Fixes bugs without intentionally breaking the compatibility guarantees of the current generation.
Within an ecosystem generation, the bytecode format, opcode operands, and opcode semantics must remain compatible. A minor release must not introduce a public bytecode feature that requires a newer virtual machine to execute.
This ensures that bytecode produced by any CandleC release within a generation remains compatible with every CandleVM release of that generation, regardless of their minor or patch versions, subject to documented exceptions for bugs and other explicitly specified cases.
For example, a program compiled with CandleC 1.2.0 must remain compatible with CandleVM 1.5.0, provided both implement the Candle 1 bytecode specification correctly.
CandleSys and CandleStd
CandleSys and CandleStd prioritize independent evolution while preserving compatibility within an ecosystem generation.
Their versions also follow the MAJOR.MINOR.PATCH format, but their versioning rules differ:
- MAJOR — Identifies the ecosystem generation and changes that break compatibility.
- MINOR — Introduces new public features and other backward-compatible improvements.
- PATCH — Fixes bugs without introducing breaking changes.
Unlike CandleVM and CandleC, CandleSys and CandleStd may introduce new public functionality in minor releases. This is possible because developers can specify the exact versions of these components required by their projects in their candlec.toml configuration files (for plugins) or directly by adding the libraries files in their project.
A program can therefore declare a specific CandleSys or CandleStd version when it relies on functionality introduced in that release, rather than requiring every release within the same ecosystem generation to provide identical functionality.
For example, a project using a feature introduced in CandleSys 1.2.0 can explicitly target that version. It does not need to assume that every CandleSys 1.x release provides the same set of features.