Versioning by Sdoba16 · Pull Request #263 · BlockstreamResearch/SimplicityHL

Sdoba16 · 2026-03-31T10:20:51Z

Closes #248

Add compiler versioning for SimplicityHL contracts

This PR introduces strict compiler version requirements

Version Directives: Every .simf file must now begin with a simc "..." directive. The directive is safely extracted (ignoring comments) and validated before full AST construction.
SemVer Ranges: Added support for standard Semantic Versioning ranges (e.g., >=0.6.0, ^0.6.0, ~0.6.0)
Dependency Versioning: The compiler driver now verifies version compatibility across the entire multi-file project (main.simf and all imported --dep libraries)
Developer Tooling: Added update_examples.py and a CI workflow to easily manage version across all examples and tests.

Syntax:

simc ">=0.6.0";

fn main() {
    ...
}

Needed simplex addition for this PR:

Version Installer: Tooling that will go through the dependencies and look for best fitting version to be installed. The tool will take existing versions from HL releases and install the best-fitted one.

stringhandler

Concept ACK.

I've come around to the idea that users should optionally be able to specify the compiler version. However, I don't like the pragma keyword as it deviates from rust, which we haven't done previously. Below are some suggestions.

I also don't think it should be required in the .simc, which will allow us to specify it in a project level manifest for when multiple files are included and for libraries in future. Also, the user should not be forced to provided it even in a single file scenario. This is just extra friction for new developers.

stringhandler · 2026-04-01T08:34:44Z

@@ -1,3 +1,5 @@
+pragma version 0.5.0-rc.0;


should we maybe rather use a global attribute syntax

#![version("0.5.0-rc.0")]

I would also suggest naming it compiler-version or simc_version or even just simc, so that users don't think it is annotating this file with a version.

stringhandler · 2026-04-01T08:39:08Z

 /// Records _what_ happened but not where.
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub enum Error {
+    VersionMismatch {


Suggested change

VersionMismatch {

SimcVersionMismatch {

I prefer stating that it's the compiler version here as well

stringhandler · 2026-04-01T08:39:42Z

+
+                let insertion_point = Span::new(first_item_span.start, first_item_span.start);
+
+                return Err(Error::MissingPragma {


I think pragmas should be optional

stringhandler · 2026-04-01T08:40:23Z

+        expected: String,
+        compiler: String,
+    },
+    MissingPragma {


I don't think stating the compiler version should be required

apoelstra · 2026-04-03T06:40:29Z

ab41fec needs rebase

KyrylR · 2026-05-08T09:17:37Z

Do we have an issue for discussion this?

Sdoba16 · 2026-05-08T09:21:50Z

Do we have an issue for discussion this?

#248

KyrylR · 2026-06-01T08:25:13Z

Needs rebase

apoelstra · 2026-06-01T08:37:36Z

c56e75d needs rebase

stringhandler · 2026-06-04T09:55:04Z

Is it required to add the compiler version? I would say the examples should only specify the minimum version needed to compile, which for all of these would not be necessary as they don't have any breaking changes. The only ones that might need to be specified are the ones using the use and pub keywords.

It is generally fine to include a compiler version, but these look like they need to keep being updated.

stringhandler · 2026-06-08T14:25:32Z

@@ -1,3 +1,5 @@
+simc ">=0.6.0";


Should this not just be simc "0.6.0"?

Can we guarantee it will work on 0.7.0?

I explained the reason here: #263 (comment)

stringhandler · 2026-06-08T14:26:34Z

+
+The SimplicityHL compiler enforces strict version compatibility to prevent contracts from silently breaking due to compiler updates, semantic changes, or new language features. 
+
+Every `.simf` file must begin with a compiler version directive:


Suggested change

Every `.simf` file must begin with a compiler version directive:

Every `.simf` file may begin with a compiler version directive:

I think it is incredibly limiting to new developers to enforce this. Surely this should be opt-in.

I do not fully understand how it will work. If we load a file without a version, then how are we supposed to determine it? Do we assume that it is always correct? What if the functionality in that file becomes deprecated? What if we have some vulnerabilities in the file? Thus, I think we need to make it mandatory for users to use versions

Let me walk through the two concrete scenarios:

Case 1: File uses newer syntax (e.g., pub or use, introduced in simc 0.6.0)
If no version is specified, the file simply fails to compile on older compilers with a syntax error. The simc field doesn't change this outcome - it just gives a much better error message ("this file requires simc >= 0.6.0") instead of a confusing parser error.

Case 2: File uses deprecated or removed functionality
Same story: without a version constraint, the file fails to compile once that feature is removed. The simc field lets authors signal simc >=0.5.0, <0.6.0 to make that explicit, but it's still an error either way.

On vulnerabilities: the simc version field controls compilation compatibility, not runtime security. Vulnerabilities in Simplicity programs are addressed at the consensus/jet layer, independently of the compiler version.

So omitting the simc field is never silently wrong - the compiler still catches incompatibilities. Making it mandatory adds friction for new developers who just want to write a simple program, and requires them to understand version semantics before writing their first line of code. Keeping it as may means it's there when you need better error messages, but doesn't block the happy path.

Got it, okay

stringhandler · 2026-06-08T14:28:46Z

        for (path, content) in files {
            let full_path = format!("workspace/{}", path);
-            let created_file = canon(&ws.create_file(&full_path, content));
+            let injected_content = if crate::version::has_version_header(content)


This could use a comment.

stringhandler · 2026-06-08T14:31:32Z

+
+version_test!(
+    exact_match_all, true, None,
+    "main.simf" => "simc \"={v}\";\nuse lib::A::foo;\nfn main() {}",


Suggested change

"main.simf" => "simc \"={v}\";\nuse lib::A::foo;\nfn main() {}",

"main.simf" => r#"simc ""={v}"";

use lib::A::foo;

fn main() {}"#,

These would be much easier to review if you use raw strings

apoelstra · 2026-06-08T14:36:33Z

cd5b1e9 needs rebase

LesterEvSe · 2026-07-01T09:43:16Z

+/// Replace the directive with equal-length spaces so the parser never sees it
+/// while later byte offsets (and thus error spans) stay correct.
+pub(crate) fn blank_version_directive(content: &str) -> Cow<'_, str> {


This function answers the question "What does this function do?", but not "Why was this function needed?". I looked at the following commits to see its usage inside the parse.rs file, but I still do not understand the reason for using it

LesterEvSe · 2026-07-01T13:46:11Z

+    /// A directive-looking line that is not a well-formed `simc "...";`.
+    Malformed(Span),
+    /// More than one directive.
+    Duplicate(Span),
+    /// A well-formed directive that appears after program code.
+    Misplaced(Span),


Let's stick to the style that was mentioned here: #328 (comment)

LesterEvSe · 2026-07-01T14:07:19Z


    #[test]
    fn test_debug_and_jet_tracing() {
+        let program_text = TEST_PROGRAM;


I do not think we need to change this file at all

Sdoba16 closed this Mar 31, 2026

Sdoba16 reopened this Mar 31, 2026

Sdoba16 self-assigned this Mar 31, 2026

stringhandler reviewed Apr 1, 2026

View reviewed changes

Sdoba16 force-pushed the feature/versions branch 3 times, most recently from ef379ee to 975817b Compare April 6, 2026 10:59

Sdoba16 force-pushed the feature/versions branch from 975817b to 48917f7 Compare May 4, 2026 13:23

Sdoba16 requested review from apoelstra May 4, 2026 13:41

Sdoba16 force-pushed the feature/versions branch from e4551f5 to c56e75d Compare May 4, 2026 13:56

Sdoba16 marked this pull request as ready for review May 5, 2026 08:17

Sdoba16 requested a review from delta1 as a code owner May 5, 2026 08:17

LesterEvSe linked an issue May 15, 2026 that may be closed by this pull request

Feature: Versioning #248

Open

Sdoba16 force-pushed the feature/versions branch from c56e75d to 18ab20c Compare June 3, 2026 16:57

LesterEvSe requested changes Jun 4, 2026

View reviewed changes

Comment thread doc/versioning.md Outdated

Comment thread doc/versioning.md Outdated

Comment thread src/driver/version_tests.rs Outdated

Comment thread src/driver/version_tests.rs Outdated

Sdoba16 force-pushed the feature/versions branch from 18ab20c to cd5b1e9 Compare June 4, 2026 14:22

Sdoba16 mentioned this pull request Jun 5, 2026

Add function versioning for better library management #349

Open

stringhandler reviewed Jun 8, 2026

View reviewed changes

Sdoba16 marked this pull request as draft June 26, 2026 09:07

Sdoba16 force-pushed the feature/versions branch 3 times, most recently from 521e33f to 1ac6efd Compare June 29, 2026 10:03

Sdoba16 force-pushed the feature/versions branch 2 times, most recently from a413ba1 to fed34ae Compare July 1, 2026 07:17

Sdoba16 marked this pull request as ready for review July 1, 2026 07:28

Sdoba16 requested a review from LesterEvSe July 1, 2026 07:32

Sdoba16 added 4 commits July 1, 2026 10:24

Add version checking engine

c1a426c

Integrate version checking engine into compiler

cdb618f

Add version tests for multi-file resolution

f12923a

Add documentation for versioning

948b18d

Sdoba16 force-pushed the feature/versions branch from fed34ae to 948b18d Compare July 1, 2026 08:47

LesterEvSe requested changes Jul 1, 2026

View reviewed changes

LesterEvSe reviewed Jul 1, 2026

View reviewed changes


		let insertion_point = Span::new(first_item_span.start, first_item_span.start);

		return Err(Error::MissingPragma {


		The SimplicityHL compiler enforces strict version compatibility to prevent contracts from silently breaking due to compiler updates, semantic changes, or new language features.

		Every `.simf` file must begin with a compiler version directive:

	Every `.simf` file must begin with a compiler version directive:
	Every `.simf` file may begin with a compiler version directive:

Uh oh!

Conversation

Sdoba16 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stringhandler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apoelstra commented Apr 3, 2026

Uh oh!

KyrylR commented May 8, 2026

Uh oh!

Sdoba16 commented May 8, 2026

Uh oh!

KyrylR commented Jun 1, 2026

Uh oh!

apoelstra commented Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stringhandler commented Jun 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apoelstra commented Jun 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LesterEvSe Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Sdoba16 commented Mar 31, 2026 •

edited

Loading

LesterEvSe Jul 1, 2026 •

edited

Loading