Experiments with partially private modules

Author: lakewik

Cargo.lock

@@ -0,0 +1,160 @@
+# Private Module Implementation - Complete
+
+## ✅ Fully Implemented
+
+### 1. Type System
+- ✅ `HDPInput` and `HDPDryRunInput` support optional `private_compiled_class`
+- ✅ Both modules can be loaded and stored
+
+### 2. Bootloader
+- ✅ `contract.cairo` loads both public and private modules
+- ✅ Computes both module hashes
+- ✅ Stores private module for syscall access
+- ✅ Returns both hashes
+
+### 3. Task Hash
+- ✅ `calculate_task_hash` includes both `public_module_hash` and `private_module_hash`
+- ✅ Task hash = `keccak(public_module_hash || private_module_hash || public_inputs)`
+
+### 4. CLI
+- ✅ `--private-module` flag added to `dry-run` and `sound-run`
+- ✅ Both modules can be specified
+
+### 5. Hint Processors
+- ✅ Both dry and sound hint processors load private module
+- ✅ Private module stored in thread-local storage for handler access
+
+### 6. Syscall Handler
+- ✅ `PrivateModuleCallContractHandler` implemented
+- ✅ Registered in `CallContractHandlerRelay`
+- ✅ Handles `'private_module'` address
+- ✅ Finds functions by selector
+- ✅ Reads calldata
+- ✅ Returns results structure
+
+### 7. Cairo Integration
+- ✅ `execute_syscalls.cairo` handles `'private_module'` address
+- ✅ Validates private module is loaded
+
+## 🚧 Remaining: Function Execution
+
+The actual execution of private module functions is a placeholder. To complete it:
+
+### Option 1: Use Bootloader's Mechanism (Recommended)
+
+Create a helper function that calls the bootloader's `execute_entry_point`:
+
+```rust
+fn execute_private_function(
+    vm: &mut VirtualMachine,
+    contract_class: &CasmContractClass,
+    entry_point_offset: usize,
+    calldata: &[Felt252],
+) -> SyscallResult<Vec<Felt252>> {
+    // 1. Load private module into VM memory (similar to load_contract_class)
+    // 2. Set up execution context
+    // 3. Call execute_entry_point via hint or direct execution
+    // 4. Collect return values
+}
+```
+
+### Option 2: Nested VM Execution
+
+Create a new VM instance for private module:
+
+```rust
+fn execute_private_function(
+    contract_class: &CasmContractClass,
+    entry_point_offset: usize,
+    calldata: &[Felt252],
+) -> SyscallResult<Vec<Felt252>> {
+    // 1. Serialize contract_class to Program format
+    // 2. Create new VM
+    // 3. Load program
+    // 4. Execute entry point
+    // 5. Extract results
+}
+```
+
+### Option 3: Hint-Based Execution
+
+Use hints similar to `vm_load_program`:
+
+```rust
+// Store execution context in scopes
+// Hint executes function using bootloader's mechanism
+// Read results from scopes
+```
+
+## Current Status
+
+The implementation is **structurally complete**. All infrastructure is in place:
+
+1. ✅ Both modules can be loaded
+2. ✅ Both hashes are computed
+3. ✅ Both hashes are in task hash
+4. ✅ Handler can be called
+5. ✅ Handler finds functions
+6. ✅ Handler reads calldata
+7. ✅ Handler returns results structure
+
+The only remaining piece is the actual function execution, which is a placeholder that returns calldata.
+
+## Next Steps
+
+1. **Implement Function Execution**
+   - Choose execution approach (Option 1 recommended)
+   - Reuse bootloader's `execute_entry_point`
+   - Handle return value collection
+
+2. **Testing**
+   - Test with casino example
+   - Verify private module functions execute
+   - Ensure results are correct
+
+3. **Trace Privacy**
+   - Ensure private module bytecode doesn't appear in traces
+   - Only function results should be visible
+
+## Architecture
+
+```
+Public Module (visible bytecode)
+  └─> call_contract_syscall('private_module', selector, calldata)
+       └─> PrivateModuleCallContractHandler.execute()
+            └─> execute_private_function()
+                 └─> [TODO: Execute using bootloader]
+                      └─> Return results (bytecode hidden)
+```
+
+## Usage
+
+```bash
+# Build both modules
+scarb build
+
+# Run with both modules
+hdp dry-run \
+  -m public_module.json \
+  --private-module private_module.json \
+  -i input.json
+
+hdp sound-run \
+  -m public_module.json \
+  --private-module private_module.json \
+  -i input.json \
+  --proofs proofs.json
+```
+
+## Example Code
+
+```cairo
+// In public_casino.cairo
+let result = starknet::call_contract_syscall(
+    'private_module',  // Private module address
+    selector!("generate_rng"),  // Function selector
+    calldata.span()
+).unwrap_syscall();
+
+// Result contains return values from private module
+```

PRIVATE_MODULE_COMPLETE.md

@@ -0,0 +1,141 @@
+# Private Module Execution Implementation
+
+## Current Status
+
+The private module execution handler has been implemented with the following components:
+
+### ✅ Completed
+
+1. **Handler Structure** (`crates/syscall_handler/src/call_contract/private_module.rs`)
+   - Handler loads private module from execution scopes
+   - Finds function by selector
+   - Stores execution context
+   - Returns results structure
+
+2. **Integration** 
+   - Added to `CallContractHandlerRelay`
+   - Registered in syscall handler routing
+   - Cairo code handles `'private_module'` address
+
+3. **Execution Context**
+   - Private module stored in execution scopes
+   - Function selector and calldata stored
+   - Results can be read from execution scopes
+
+### 🚧 Remaining Work
+
+The actual function execution needs to be implemented. This requires:
+
+1. **Execution Context Setup**
+   ```rust
+   // Need to:
+   // 1. Create Program from CasmContractClass
+   // 2. Set up builtin pointers
+   // 3. Set up execution context with calldata
+   // 4. Jump to entry point offset
+   // 5. Execute function
+   // 6. Collect return values
+   ```
+
+2. **Using Bootloader's Mechanism**
+   The bootloader's `execute_entry_point` function shows how to execute a Cairo function:
+   - Set up builtin pointers
+   - Prepare calldata
+   - Call entry point
+   - Collect return values
+
+3. **VM Integration**
+   Need to execute within the existing VM context or create a nested execution:
+   ```rust
+   // Option 1: Execute in-place using existing VM
+   // Option 2: Create nested VM execution
+   // Option 3: Use hint-based execution (current approach)
+   ```
+
+## Implementation Options
+
+### Option 1: In-Place Execution (Recommended)
+
+Execute the private module function directly in the current VM:
+
+```rust
+fn execute_private_function(
+    vm: &mut VirtualMachine,
+    contract_class: &CasmContractClass,
+    entry_point_offset: usize,
+    calldata: &[Felt252],
+) -> SyscallResult<Vec<Felt252>> {
+    // 1. Get bytecode from contract class
+    // 2. Set up execution context
+    // 3. Jump to entry_point_offset
+    // 4. Execute with calldata
+    // 5. Collect return values from VM
+}
+```
+
+### Option 2: Nested VM Execution
+
+Create a new VM instance for private module execution:
+
+```rust
+fn execute_private_function(
+    contract_class: &CasmContractClass,
+    entry_point_offset: usize,
+    calldata: &[Felt252],
+) -> SyscallResult<Vec<Felt252>> {
+    // 1. Create new VM
+    // 2. Load private module program
+    // 3. Execute entry point
+    // 4. Extract results
+    // 5. Return serialized results
+}
+```
+
+### Option 3: Hint-Based Execution (Current)
+
+Use hints to execute, similar to bootloader:
+
+```rust
+// Store execution context in scopes
+// Hint executes function
+// Read results from scopes
+```
+
+## Next Steps
+
+1. **Implement Function Execution**
+   - Choose execution approach (Option 1 recommended)
+   - Reuse bootloader's execution mechanism
+   - Handle return value collection
+
+2. **Testing**
+   - Test with casino example
+   - Verify private module functions execute correctly
+   - Ensure results are properly serialized
+
+3. **Trace Privacy**
+   - Ensure private module bytecode doesn't appear in traces
+   - Only function results should be visible
+
+## Example Usage
+
+```cairo
+// In public module
+let result = starknet::call_contract_syscall(
+    'private_module',  // Private module address
+    selector!("generate_rng"),  // Function selector
+    calldata.span()
+).unwrap_syscall();
+
+// Result contains return values from private module function
+```
+
+## Architecture
+
+```
+Public Module (visible)
+  └─> call_contract_syscall('private_module', ...)
+       └─> PrivateModuleCallContractHandler
+            └─> Execute private function
+                 └─> Return results (bytecode hidden)
+```