external jets loading

Author: ivanlele

.github/workflows/rust.yml

@@ -106,3 +106,22 @@ jobs:
             echo "fuzzing $target"
             cargo fuzz run --fuzz-dir fuzz "$target" -- -runs=1
           done
+
+  ExternalJetLib:
+    name: External Jet Library
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repo"
+        uses: actions/checkout@v4
+
+      - name: "Setup cargo-rbmt"
+        uses: ./.github/actions/setup-rbmt
+
+      - name: "Build external jet dylib"
+        run: cargo rbmt --lock-file existing run --toolchain stable -- build --manifest-path external-jet-lib-example/Cargo.toml --lib
+
+      - name: "Build external-lib-consumer binary"
+        run: cargo rbmt --lock-file existing run --toolchain stable -- build --manifest-path external-jet-lib-example/Cargo.toml --bin external-lib-consumer
+
+      - name: "Run external-lib-consumer with compiled dylib"
+        run: ./target/debug/external-lib-consumer ./target/debug/libexternal_jet_lib_example.so

Cargo.lock

@@ -31,6 +31,7 @@ required-features = ["docs", "serde"]
 default = [ "serde" ]
 serde = ["dep:serde", "dep:serde_json"]
 docs = []
+external-jets = []
 
 [dependencies]
 base64 = "0.21.2"
@@ -48,7 +49,7 @@ chumsky = "0.11.2"
 getrandom = { version = "0.2", features = ["js"] }
 
 [workspace]
-members = ["codegen", "fuzz"]
+members = ["codegen", "fuzz", "external-jet-lib-example"]
 exclude = ["bitcoind-tests"]
 
 [workspace.metadata.rbmt.toolchains]

Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "external-jet-lib-example"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.79.0"
+
+[[bin]]
+name = "external-lib-consumer"
+path = "src/main.rs"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+simplicityhl = { path = "..", features = ["external-jets"] }

external-jet-lib-example/Cargo.toml

@@ -0,0 +1,57 @@
+# External Jet Loading
+
+SimplicityHL supports loading custom jet sets at runtime from a shared library (`.so` / `.dylib` / `.dll`). This crate is an end-to-end example of how to build such a library and consume it.
+
+## How It Works
+
+### 1. Enable the feature flag
+
+The external jet machinery lives behind the `external-jets` Cargo feature in the main `simplicityhl` crate. Both the library and its consumer must opt in:
+
+```toml
+[dependencies]
+simplicityhl = { path = "..", features = ["external-jets"] }
+```
+
+### 2. Build a `cdylib` that exports the required symbols
+
+See [src/lib.rs](src/lib.rs) and [src/jet.rs](src/jet.rs) for a minimal implementation with a single `verify` jet.
+
+### 3. Initialize the library at program startup
+
+Before compiling any Simplicity programs, call `init_external_jet_lib` with the path to the compiled `.so` / `.dylib` / `.dll`:
+
+```rust
+unsafe {
+    simplicityhl::jet::external::init_external_jet_lib("/path/to/libexternal_jet_lib_example.dylib")
+        .expect("failed to load external jet lib");
+}
+```
+
+### 4. Pass `ExternalJetHinter` to the compiler
+
+`ExternalJetHinter` implements `JetHinter` and delegates `parse_jet` / `construct_verify` to the loaded library. Pass it when constructing a `TemplateProgram`:
+
+```rust
+use simplicityhl::{jet::external::ExternalJetHinter, TemplateProgram};
+
+let program = TemplateProgram::new(simf_code, Box::new(ExternalJetHinter::new()))
+    .expect("compilation failed");
+```
+
+The compiler will call `parse_jet` whenever it encounters an unknown jet name, forwarding the lookup to your shared library.
+
+## Building the Example
+
+```sh
+# Build the shared library
+cargo build -p external-jet-lib-example
+
+# Run the consumer binary, pointing it at the compiled dylib
+cargo run -p external-jet-lib-example --bin external-lib-consumer -- \
+    target/debug/libexternal_jet_lib_example.dylib
+```
+
+## Security Notes
+
+Loading a shared library executes arbitrary native code in the current process. Only load libraries from trusted, verified sources.

external-jet-lib-example/README.md

@@ -0,0 +1,132 @@
+use std::io::Write;
+
+use simplicityhl::{
+    jet::{JetHL, SourceJetClassification, TargetJetClassification},
+    simplicity::{
+        decode::Error,
+        decode_bits,
+        jet::{type_name::TypeName, Jet},
+        BitIter, BitWriter, Cmr, Cost, Error as SimplicityError,
+    },
+};
+
+pub struct ExternalJet {
+    pub index: u64,
+}
+
+#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
+pub enum HappyJet {
+    Verify,
+}
+
+impl HappyJet {
+    pub fn index(&self) -> u64 {
+        match self {
+            HappyJet::Verify => 0,
+        }
+    }
+
+    pub fn from_index(index: u64) -> Option<Self> {
+        match index {
+            0 => Some(HappyJet::Verify),
+            _ => None,
+        }
+    }
+}
+
+impl Jet for HappyJet {
+    fn cmr(&self) -> Cmr {
+        let bytes = match self {
+            HappyJet::Verify => [
+                0xcd, 0xca, 0x2a, 0x05, 0xe5, 0x2c, 0xef, 0xa5, 0x9d, 0xc7, 0xa5, 0xb0, 0xda, 0xe2,
+                0x20, 0x98, 0xfb, 0x89, 0x6e, 0x39, 0x13, 0xbf, 0xdd, 0x44, 0x6b, 0x59, 0x4e, 0x1f,
+                0x92, 0x50, 0x78, 0x3e,
+            ],
+        };
+        Cmr::from_byte_array(bytes)
+    }
+
+    fn source_ty(&self) -> TypeName {
+        let name: &'static [u8] = match self {
+            HappyJet::Verify => b"2",
+        };
+
+        TypeName(name)
+    }
+
+    fn target_ty(&self) -> TypeName {
+        let name: &'static [u8] = match self {
+            HappyJet::Verify => b"1",
+        };
+
+        TypeName(name)
+    }
+
+    fn encode(&self, w: &mut BitWriter<&mut dyn Write>) -> std::io::Result<usize> {
+        let (n, len) = match self {
+            HappyJet::Verify => (0, 1),
+        };
+
+        w.write_bits_be(n, len)
+    }
+
+    fn decode<I: Iterator<Item = u8>>(bits: &mut BitIter<I>) -> Result<Self, Error>
+    where
+        Self: Sized,
+    {
+        decode_bits!(bits, {
+            0 => {HappyJet::Verify},
+            1 => {}
+        })
+    }
+
+    fn cost(&self) -> Cost {
+        match self {
+            HappyJet::Verify => Cost::from_milliweight(44),
+        }
+    }
+
+    fn parse(s: &str) -> Result<Self, SimplicityError>
+    where
+        Self: Sized,
+    {
+        match s {
+            "verify" => Ok(HappyJet::Verify),
+            x => Err(SimplicityError::InvalidJetName(x.to_owned())),
+        }
+    }
+}
+
+impl std::fmt::Display for HappyJet {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        match self {
+            HappyJet::Verify => write!(f, "verify"),
+        }
+    }
+}
+
+impl JetHL for HappyJet {
+    fn source_jet_classification(&self) -> SourceJetClassification {
+        match self {
+            HappyJet::Verify => SourceJetClassification::Custom(vec![simplicityhl::jet::bool()]),
+        }
+    }
+
+    fn target_jet_classification(&self) -> TargetJetClassification {
+        match self {
+            HappyJet::Verify => TargetJetClassification::Unary,
+        }
+    }
+
+    fn is_disabled(&self) -> bool {
+        false
+    }
+
+    fn clone_box(&self) -> Box<dyn JetHL> {
+        Box::new(*self)
+    }
+
+    fn as_jet(&self) -> &dyn Jet {
+        self
+    }
+}

external-jet-lib-example/src/jet.rs

@@ -0,0 +1,96 @@
+use std::io::Write;
+
+use simplicityhl::{
+    jet::{JetHL, SourceJetClassification, TargetJetClassification},
+    simplicity::{
+        jet::{type_name::TypeName, Jet},
+        BitWriter, Cmr, Cost,
+    },
+};
+
+use crate::jet::{ExternalJet, HappyJet};
+
+mod jet;
+
+#[no_mangle]
+pub fn cmr(jet: ExternalJet) -> Cmr {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.cmr()
+}
+
+#[no_mangle]
+pub fn source_ty(jet: ExternalJet) -> TypeName {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.source_ty()
+}
+
+#[no_mangle]
+pub fn target_ty(jet: ExternalJet) -> TypeName {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.target_ty()
+}
+
+#[no_mangle]
+pub fn encode(jet: ExternalJet, w: &mut dyn Write) -> std::io::Result<usize> {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    let mut bit_writer = BitWriter::new(w);
+
+    jet.encode(&mut bit_writer)
+}
+
+#[no_mangle]
+pub fn cost(jet: ExternalJet) -> Cost {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.cost()
+}
+
+#[no_mangle]
+pub fn parse(s: &str) -> Result<ExternalJet, simplicityhl::simplicity::Error> {
+    HappyJet::parse(s).map(|jet| ExternalJet { index: jet.index() })
+}
+#[no_mangle]
+pub fn display(jet: ExternalJet) -> String {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.to_string()
+}
+
+#[no_mangle]
+pub fn source_jet_classification(jet: ExternalJet) -> SourceJetClassification {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.source_jet_classification()
+}
+
+#[no_mangle]
+pub fn target_jet_classification(jet: ExternalJet) -> TargetJetClassification {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.target_jet_classification()
+}
+
+#[no_mangle]
+pub fn is_disabled(jet: ExternalJet) -> bool {
+    let jet = HappyJet::from_index(jet.index).expect("invalid jet index");
+
+    jet.is_disabled()
+}
+
+#[no_mangle]
+pub fn verify() -> ExternalJet {
+    let jet = HappyJet::Verify;
+
+    ExternalJet { index: jet.index() }
+}
+
+#[no_mangle]
+pub fn conjure(jet: &dyn Jet) -> Option<Box<dyn JetHL>> {
+    jet.as_any()
+        .downcast_ref::<HappyJet>()
+        .map(|jet| Box::new(*jet) as Box<dyn JetHL>)
+}

external-jet-lib-example/src/lib.rs

@@ -0,0 +1,21 @@
+use simplicityhl::{jet::external::ExternalJetHinter, TemplateProgram};
+
+fn main() {
+    let lib_path = std::env::args().nth(1).expect(
+        "Please provide the path to the compiled external jet library as the first argument",
+    );
+
+    unsafe {
+        simplicityhl::jet::external::init_external_jet_lib(&lib_path)
+            .expect("failed to initialize external jet lib");
+    }
+
+    let code = r#"fn main() {
+    assert!(true);
+}"#;
+
+    let _ = TemplateProgram::new(code, Box::new(ExternalJetHinter::new()))
+        .expect("failed to compile code with external jets");
+
+    println!("External jets were successfully used to compile:\n{}", code);
+}