feat(cli): Log and replay oracle transcript

.github/actions/download-noir-execute/action.yml

@@ -0,0 +1,18 @@
+name: Download noir-execute
+description: Downloads the noir-execute binary from an artifact and adds it to the path
+
+runs:
+  using: composite
+  steps:
+    - name: Download noir-execute binary
+      uses: actions/download-artifact@v4
+      with:
+        name: noir-execute
+        path: ./noir-execute
+
+    - name: Set noir-execute on PATH
+      shell: bash
+      run: |
+        noir_binary="${{ github.workspace }}/noir-execute/noir-execute"
+        chmod +x $noir_binary
+        echo "$(dirname $noir_binary)" >> $GITHUB_PATH

.github/workflows/test-js-packages.yml

@@ -78,6 +78,39 @@ jobs:
           path: ./dist/*
           retention-days: 3
 
+  build-noir-execute:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout Noir repo
+        uses: actions/checkout@v4
+
+      - name: Setup toolchain
+        uses: dtolnay/[email protected]
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: x86_64-unknown-linux-gnu
+          cache-on-failure: true
+          save-if: ${{ github.event_name != 'merge_group' }}
+
+      - name: Build noir-execute
+        run: cargo build --package noir_artifact_cli --release
+
+      - name: Package artifacts
+        run: |
+          mkdir dist
+          cp ./target/release/noir-execute ./dist/noir-execute
+          7z a -ttar -so -an ./dist/* | 7z a -si ./noir-execute-x86_64-unknown-linux-gnu.tar.gz
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: noir-execute
+          path: ./dist/*
+          retention-days: 3
+
   build-noirc-abi:
     runs-on: ubuntu-22.04
     timeout-minutes: 30
@@ -457,7 +490,7 @@ jobs:
   test-examples:
     name: Example scripts
     runs-on: ubuntu-22.04
-    needs: [build-nargo]
+    needs: [build-nargo, build-noir-execute]
     timeout-minutes: 30
 
     steps:
@@ -477,6 +510,9 @@ jobs:
       - name: Download nargo binary
         uses: ./.github/actions/download-nargo
 
+      - name: Download noir-execute binary
+        uses: ./.github/actions/download-noir-execute
+
       - name: Run `prove_and_verify`
         working-directory: ./examples/prove_and_verify
         run: ./test.sh
@@ -485,6 +521,10 @@ jobs:
         working-directory: ./examples/codegen_verifier
         run: ./test.sh
 
+      - name: Run `oracle_transcript`
+        working-directory: ./examples/oracle_transcript
+        run: ./test.sh
+
   external-repo-checks:
     needs: [build-nargo, critical-library-list]
     runs-on: ubuntu-22.04

examples/oracle_transcript/Nargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "oracle_transcript"
+type = "bin"
+authors = [""]
+compiler_version = ">=0.23.0"
+
+[dependencies]

examples/oracle_transcript/Oracle.jsonl

@@ -0,0 +1,5 @@
+{"call":{"function":"void_field","inputs":[]},"result":{"values":["000000000000000000000000000000000000000000000000000000000000000a"]}}
+{"call":{"function":"void_field","inputs":[]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000014"]}}
+{"call":{"function":"field_field","inputs":["0000000000000000000000000000000000000000000000000000000000000002"]},"result":{"values":["000000000000000000000000000000000000000000000000000000000000001e"]}}
+{"call":{"function":"field_field","inputs":["0000000000000000000000000000000000000000000000000000000000000003"]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000028"]}}
+{"call":{"function":"struct_field","inputs":["000000000000000000000000000000000000000000000000000000000000012c","0000000000000000000000000000000000000000000000000000000000000320",["000000000000000000000000000000000000000000000000000000000000000a","0000000000000000000000000000000000000000000000000000000000000014","000000000000000000000000000000000000000000000000000000000000001e","0000000000000000000000000000000000000000000000000000000000000028"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000064"]}}

examples/oracle_transcript/Oracle.test.jsonl

@@ -0,0 +1,20 @@
+{"call":{"function":"create_mock","inputs":[["0000000000000000000000000000000000000000000000000000000000000076","000000000000000000000000000000000000000000000000000000000000006f","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000064","000000000000000000000000000000000000000000000000000000000000005f","0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000000"]}}
+{"call":{"function":"set_mock_returns","inputs":["0000000000000000000000000000000000000000000000000000000000000000","000000000000000000000000000000000000000000000000000000000000000a"]},"result":{"values":[]}}
+{"call":{"function":"set_mock_times","inputs":["0000000000000000000000000000000000000000000000000000000000000000","0000000000000000000000000000000000000000000000000000000000000001"]},"result":{"values":[]}}
+{"call":{"function":"create_mock","inputs":[["0000000000000000000000000000000000000000000000000000000000000076","000000000000000000000000000000000000000000000000000000000000006f","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000064","000000000000000000000000000000000000000000000000000000000000005f","0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000001"]}}
+{"call":{"function":"set_mock_returns","inputs":["0000000000000000000000000000000000000000000000000000000000000001","0000000000000000000000000000000000000000000000000000000000000014"]},"result":{"values":[]}}
+{"call":{"function":"set_mock_times","inputs":["0000000000000000000000000000000000000000000000000000000000000001","0000000000000000000000000000000000000000000000000000000000000001"]},"result":{"values":[]}}
+{"call":{"function":"create_mock","inputs":[["0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064","000000000000000000000000000000000000000000000000000000000000005f","0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000002"]}}
+{"call":{"function":"set_mock_params","inputs":["0000000000000000000000000000000000000000000000000000000000000002","0000000000000000000000000000000000000000000000000000000000000002"]},"result":{"values":[]}}
+{"call":{"function":"set_mock_returns","inputs":["0000000000000000000000000000000000000000000000000000000000000002","000000000000000000000000000000000000000000000000000000000000001e"]},"result":{"values":[]}}
+{"call":{"function":"create_mock","inputs":[["0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064","000000000000000000000000000000000000000000000000000000000000005f","0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000003"]}}
+{"call":{"function":"set_mock_params","inputs":["0000000000000000000000000000000000000000000000000000000000000003","0000000000000000000000000000000000000000000000000000000000000003"]},"result":{"values":[]}}
+{"call":{"function":"set_mock_returns","inputs":["0000000000000000000000000000000000000000000000000000000000000003","0000000000000000000000000000000000000000000000000000000000000028"]},"result":{"values":[]}}
+{"call":{"function":"create_mock","inputs":[["0000000000000000000000000000000000000000000000000000000000000073","0000000000000000000000000000000000000000000000000000000000000074","0000000000000000000000000000000000000000000000000000000000000072","0000000000000000000000000000000000000000000000000000000000000075","0000000000000000000000000000000000000000000000000000000000000063","0000000000000000000000000000000000000000000000000000000000000074","000000000000000000000000000000000000000000000000000000000000005f","0000000000000000000000000000000000000000000000000000000000000066","0000000000000000000000000000000000000000000000000000000000000069","0000000000000000000000000000000000000000000000000000000000000065","000000000000000000000000000000000000000000000000000000000000006c","0000000000000000000000000000000000000000000000000000000000000064"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000004"]}}
+{"call":{"function":"set_mock_params","inputs":["0000000000000000000000000000000000000000000000000000000000000004","000000000000000000000000000000000000000000000000000000000000012c","0000000000000000000000000000000000000000000000000000000000000320",["000000000000000000000000000000000000000000000000000000000000000a","0000000000000000000000000000000000000000000000000000000000000014","000000000000000000000000000000000000000000000000000000000000001e","0000000000000000000000000000000000000000000000000000000000000028"]]},"result":{"values":[]}}
+{"call":{"function":"set_mock_returns","inputs":["0000000000000000000000000000000000000000000000000000000000000004","0000000000000000000000000000000000000000000000000000000000000064"]},"result":{"values":[]}}
+{"call":{"function":"void_field","inputs":[]},"result":{"values":["000000000000000000000000000000000000000000000000000000000000000a"]}}
+{"call":{"function":"void_field","inputs":[]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000014"]}}
+{"call":{"function":"field_field","inputs":["0000000000000000000000000000000000000000000000000000000000000002"]},"result":{"values":["000000000000000000000000000000000000000000000000000000000000001e"]}}
+{"call":{"function":"field_field","inputs":["0000000000000000000000000000000000000000000000000000000000000003"]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000028"]}}
+{"call":{"function":"struct_field","inputs":["000000000000000000000000000000000000000000000000000000000000012c","0000000000000000000000000000000000000000000000000000000000000320",["000000000000000000000000000000000000000000000000000000000000000a","0000000000000000000000000000000000000000000000000000000000000014","000000000000000000000000000000000000000000000000000000000000001e","0000000000000000000000000000000000000000000000000000000000000028"]]},"result":{"values":["0000000000000000000000000000000000000000000000000000000000000064"]}}

examples/oracle_transcript/Prover.toml

@@ -0,0 +1,6 @@
+
+[input]
+x = 2
+y = 3
+
+return = 100

examples/oracle_transcript/log_and_exec_transcript.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -eu
+
+cd $(dirname $0)
+
+# Execute the test to capture oracle calls.
+NARGO_TEST_FOREIGN_CALL_LOG=Oracle.test.jsonl nargo test
+
+# Get rid of the mock setup calls
+cat Oracle.test.jsonl \
+    | jq --slurp -r -c '.[] | select(.call.function | contains("mock") | not)' \
+    > Oracle.jsonl
+
+# Execute `main` with the Prover.toml and Oracle.jsonl files.
+nargo execute --skip-underconstrained-check --oracle-file Oracle.jsonl
+
+# Also execute through `noir-execute`
+noir-execute \
+    --artifact-path target/oracle_transcript.json \
+    --oracle-file Oracle.jsonl \
+    --prover-file Prover.toml \
+    --output-dir target

examples/oracle_transcript/src/main.nr

@@ -0,0 +1,63 @@
+use std::test::OracleMock;
+
+struct Point {
+    x: Field,
+    y: Field,
+}
+
+impl Eq for Point {
+    fn eq(self, other: Point) -> bool {
+        (self.x == other.x) & (self.y == other.y)
+    }
+}
+
+#[oracle(void_field)]
+unconstrained fn void_field_oracle() -> Field {}
+
+unconstrained fn void_field() -> Field {
+    void_field_oracle()
+}
+
+#[oracle(field_field)]
+unconstrained fn field_field_oracle(_x: Field) -> Field {}
+
+unconstrained fn field_field(x: Field) -> Field {
+    field_field_oracle(x)
+}
+
+#[oracle(struct_field)]
+unconstrained fn struct_field_oracle(_point: Point, _array: [Field; 4]) -> Field {}
+
+unconstrained fn struct_field(point: Point, array: [Field; 4]) -> Field {
+    struct_field_oracle(point, array)
+}
+
+fn main(input: Point) -> pub Field {
+    // Safety: testing context
+    unsafe {
+        let a = void_field();
+        let b = void_field();
+        let c = field_field(input.x);
+        let d = field_field(input.y);
+        let p = Point { x: a * c, y: b * d };
+        struct_field(p, [a, b, c, d])
+    }
+}
+
+/// This test is used to capture an oracle transcript, which can then be replayed
+/// during execution.
+#[test]
+fn test_main() {
+    // Safety: testing context
+    unsafe {
+        let _ = OracleMock::mock("void_field").returns(10).times(1);
+        let _ = OracleMock::mock("void_field").returns(20).times(1);
+        let _ = OracleMock::mock("field_field").with_params((2,)).returns(30);
+        let _ = OracleMock::mock("field_field").with_params((3,)).returns(40);
+        let _ = OracleMock::mock("struct_field")
+            .with_params((Point { x: 300, y: 800 }, [10, 20, 30, 40]))
+            .returns(100);
+    }
+    let output = main(Point { x: 2, y: 3 });
+    assert_eq(output, 100)
+}

examples/oracle_transcript/test.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -eu
+
+cd $(dirname $0)
+
+# This file is used for Noir CI and is not required.
+
+rm -f ./Oracle.*
+
+./log_and_exec_transcript.sh

tooling/artifact_cli/src/commands/execute_cmd.rs

@@ -8,7 +8,10 @@ use crate::{
     errors::CliError,
     execution::{self, ExecutionResults},
 };
-use nargo::{PrintOutput, foreign_calls::DefaultForeignCallBuilder};
+use nargo::{
+    PrintOutput,
+    foreign_calls::{DefaultForeignCallBuilder, layers, transcript::ReplayForeignCallExecutor},
+};
 use noirc_driver::CompiledProgram;
 
 use super::parse_and_normalize_path;
@@ -40,10 +43,27 @@ pub struct ExecuteCommand {
     #[clap(long)]
     pub contract_fn: Option<String>,
 
+    /// Path to the oracle transcript that is to be replayed during the
+    /// execution in response to foreign calls. The format is expected
+    /// to be JSON Lines, with each request/response on a separate line.
+    ///
+    /// Note that a transcript might be invalid if the inputs change and
+    /// the circuit takes a different path during execution.
+    #[clap(long, conflicts_with = "oracle_resolver")]
+    pub oracle_file: Option<PathBuf>,
+
     /// JSON RPC url to solve oracle calls.
-    #[clap(long)]
+    #[clap(long, conflicts_with = "oracle_file")]
     pub oracle_resolver: Option<String>,
 
+    /// Root directory for the RPC oracle resolver.
+    #[clap(long, value_parser = parse_and_normalize_path)]
+    pub oracle_root_dir: Option<PathBuf>,
+
+    /// Package name for the RPC oracle resolver
+    #[clap(long)]
+    pub oracle_package_name: Option<String>,
+
     /// Use pedantic ACVM solving, i.e. double-check some black-box function assumptions when solving.
     #[clap(long, default_value_t = false)]
     pub pedantic_solving: bool,
@@ -92,18 +112,23 @@ pub fn run(args: ExecuteCommand) -> Result<(), CliError> {
 
 /// Execute a circuit and return the output witnesses.
 fn execute(circuit: &CompiledProgram, args: &ExecuteCommand) -> Result<ExecutionResults, CliError> {
-    // TODO: Build a custom foreign call executor that reads from the Oracle transcript,
+    // Build a custom foreign call executor that replays the Oracle transcript,
     // and use it as a base for the default executor. Using it as the innermost rather
     // than top layer so that any extra `print` added for debugging is handled by the
     // default, rather than trying to match it to the transcript.
+    let transcript_executor = match args.oracle_file {
+        Some(ref path) => layers::Either::Left(ReplayForeignCallExecutor::from_file(path)?),
+        None => layers::Either::Right(layers::Empty),
+    };
+
     let mut foreign_call_executor = DefaultForeignCallBuilder {
         output: PrintOutput::Stdout,
         enable_mocks: false,
         resolver_url: args.oracle_resolver.clone(),
         root_path: None,
         package_name: None,
     }
-    .build();
+    .build_with_base(transcript_executor);
 
     let blackbox_solver = Bn254BlackBoxSolver(args.pedantic_solving);
 

tooling/artifact_cli/src/errors.rs

@@ -1,5 +1,5 @@
 use acir::FieldElement;
-use nargo::NargoError;
+use nargo::{NargoError, foreign_calls::transcript::TranscriptError};
 use noirc_abi::{
     AbiReturnType,
     errors::{AbiError, InputParserError},
@@ -39,6 +39,10 @@ pub enum CliError {
     #[error("Failed to deserialize inputs")]
     InputDeserializationError(#[from] InputParserError),
 
+    /// Error related to oracle transcript deserialization
+    #[error(transparent)]
+    TranscriptError(#[from] TranscriptError),
+
     /// Error related to ABI encoding
     #[error(transparent)]
     AbiError(#[from] AbiError),

tooling/nargo/src/foreign_calls/mod.rs

@@ -4,6 +4,7 @@ use thiserror::Error;
 pub mod layers;
 pub mod mocker;
 pub mod print;
+pub mod transcript;
 
 pub mod default;
 #[cfg(feature = "rpc")]
@@ -83,4 +84,7 @@ pub enum ForeignCallError {
 
     #[error("Assert message resolved after an unsatisfied constrain. {0}")]
     ResolvedAssertMessage(String),
+
+    #[error("Failed to replay oracle transcript: {0}")]
+    TranscriptError(String),
 }

tooling/nargo/src/foreign_calls/print.rs

@@ -16,6 +16,7 @@ pub enum PrintOutput<'a> {
     String(&'a mut String),
 }
 
+/// Handle `println` calls.
 #[derive(Debug, Default)]
 pub struct PrintForeignCallExecutor<'a> {
     output: PrintOutput<'a>,