final implementation before testing

Author: bengtlofgren

svm/modules/executor-requests/Cargo.lock

@@ -145,9 +145,105 @@ impl RelayInstructionsBuilder {
     }
 }
 
+// ============================================================================
+// Relay Instruction Parsing
+// ============================================================================
+
+/// Relay instruction parsing errors.
+///
+/// Discriminants are ordered to align with executor-quoter error codes (base 0x1002):
+/// - 0 -> UnsupportedInstruction (0x1002)
+/// - 1 -> MoreThanOneDropOff (0x1003)
+/// - 2 -> MathOverflow (0x1004)
+/// - 3 -> InvalidRelayInstructions (0x1005)
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RelayParseError {
+    /// Unknown relay instruction type
+    UnsupportedType = 0,
+    /// More than one drop-off instruction found
+    MultipleDropoff = 1,
+    /// Arithmetic overflow when accumulating gas_limit or msg_value
+    Overflow = 2,
+    /// Instruction data truncated / not enough bytes
+    Truncated = 3,
+}
+
+/// Parses relay instructions to extract total gas limit and msg value.
+///
+/// Returns `(gas_limit, msg_value)` on success, or `RelayParseError` on failure.
+/// Multiple gas instructions are summed. Only one dropoff is allowed.
+///
+/// Instruction format:
+/// - Type 1 (Gas): 1 byte type + 16 bytes gas_limit + 16 bytes msg_value = 33 bytes
+/// - Type 2 (DropOff): 1 byte type + 16 bytes msg_value + 32 bytes recipient = 49 bytes
+pub fn parse_relay_instructions(data: &[u8]) -> Result<(u128, u128), RelayParseError> {
+    let mut offset = 0;
+    let mut gas_limit: u128 = 0;
+    let mut msg_value: u128 = 0;
+    let mut has_drop_off = false;
+
+    while offset < data.len() {
+        let ix_type = data[offset];
+        offset += 1;
+
+        match ix_type {
+            RELAY_IX_GAS => {
+                // Gas instruction: 16 bytes gas_limit + 16 bytes msg_value
+                if offset + 32 > data.len() {
+                    return Err(RelayParseError::Truncated);
+                }
+
+                let mut ix_gas_bytes = [0u8; 16];
+                ix_gas_bytes.copy_from_slice(&data[offset..offset + 16]);
+                let ix_gas_limit = u128::from_be_bytes(ix_gas_bytes);
+                offset += 16;
+
+                let mut ix_val_bytes = [0u8; 16];
+                ix_val_bytes.copy_from_slice(&data[offset..offset + 16]);
+                let ix_msg_value = u128::from_be_bytes(ix_val_bytes);
+                offset += 16;
+
+                gas_limit = gas_limit
+                    .checked_add(ix_gas_limit)
+                    .ok_or(RelayParseError::Overflow)?;
+                msg_value = msg_value
+                    .checked_add(ix_msg_value)
+                    .ok_or(RelayParseError::Overflow)?;
+            }
+            RELAY_IX_GAS_DROP_OFF => {
+                if has_drop_off {
+                    return Err(RelayParseError::MultipleDropoff);
+                }
+                has_drop_off = true;
+
+                // DropOff instruction: 16 bytes msg_value + 32 bytes recipient
+                if offset + 48 > data.len() {
+                    return Err(RelayParseError::Truncated);
+                }
+
+                let mut ix_val_bytes = [0u8; 16];
+                ix_val_bytes.copy_from_slice(&data[offset..offset + 16]);
+                let ix_msg_value = u128::from_be_bytes(ix_val_bytes);
+                offset += 48; // Skip msg_value (16) + recipient (32)
+
+                msg_value = msg_value
+                    .checked_add(ix_msg_value)
+                    .ok_or(RelayParseError::Overflow)?;
+            }
+            _ => {
+                return Err(RelayParseError::UnsupportedType);
+            }
+        }
+    }
+
+    Ok((gas_limit, msg_value))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use alloc::vec;
 
     #[test]
     fn test_vaa_v1() {
@@ -272,4 +368,141 @@ mod tests {
         let result = RelayInstructionsBuilder::new().build();
         assert_eq!(result.len(), 0);
     }
+
+    // ========================================================================
+    // parse_relay_instructions tests
+    // ========================================================================
+
+    #[test]
+    fn test_parse_relay_instructions_empty() {
+        let result = parse_relay_instructions(&[]);
+        assert_eq!(result, Ok((0, 0)));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_gas() {
+        let data = make_relay_instruction_gas(250_000, 1_000_000);
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Ok((250_000, 1_000_000)));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_dropoff() {
+        let recipient = [0xAB; 32];
+        let data = make_relay_instruction_gas_drop_off(500_000, &recipient);
+        let result = parse_relay_instructions(&data);
+        // DropOff contributes to msg_value, not gas_limit
+        assert_eq!(result, Ok((0, 500_000)));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_gas_and_dropoff() {
+        let recipient = [0xCD; 32];
+        let data = RelayInstructionsBuilder::new()
+            .with_gas(100_000, 200_000)
+            .with_gas_drop_off(300_000, &recipient)
+            .build();
+        let result = parse_relay_instructions(&data);
+        // gas_limit = 100_000, msg_value = 200_000 + 300_000 = 500_000
+        assert_eq!(result, Ok((100_000, 500_000)));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_multiple_gas() {
+        let mut data = make_relay_instruction_gas(100_000, 50_000);
+        data.extend(make_relay_instruction_gas(200_000, 75_000));
+        data.extend(make_relay_instruction_gas(50_000, 25_000));
+        let result = parse_relay_instructions(&data);
+        // gas_limit = 100k + 200k + 50k = 350k
+        // msg_value = 50k + 75k + 25k = 150k
+        assert_eq!(result, Ok((350_000, 150_000)));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_invalid_type() {
+        let data = [0xFF, 0x00, 0x00]; // Invalid type 0xFF
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::UnsupportedType));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_truncated_gas() {
+        // Gas instruction needs 33 bytes (1 type + 16 gas_limit + 16 msg_value)
+        // Provide only 10 bytes after type
+        let mut data = vec![RELAY_IX_GAS];
+        data.extend_from_slice(&[0u8; 10]);
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::Truncated));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_truncated_dropoff() {
+        // DropOff instruction needs 49 bytes (1 type + 16 msg_value + 32 recipient)
+        // Provide only 20 bytes after type
+        let mut data = vec![RELAY_IX_GAS_DROP_OFF];
+        data.extend_from_slice(&[0u8; 20]);
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::Truncated));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_multiple_dropoff() {
+        let recipient = [0xAB; 32];
+        let mut data = make_relay_instruction_gas_drop_off(100_000, &recipient);
+        data.extend(make_relay_instruction_gas_drop_off(200_000, &recipient));
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::MultipleDropoff));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_overflow_gas_limit() {
+        let mut data = make_relay_instruction_gas(u128::MAX, 0);
+        data.extend(make_relay_instruction_gas(1, 0)); // This should overflow
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::Overflow));
+    }
+
+    #[test]
+    fn test_parse_relay_instructions_overflow_msg_value() {
+        let mut data = make_relay_instruction_gas(0, u128::MAX);
+        data.extend(make_relay_instruction_gas(0, 1)); // This should overflow
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Err(RelayParseError::Overflow));
+    }
+
+    // Roundtrip tests
+
+    #[test]
+    fn test_roundtrip_gas() {
+        let gas_limit = 1_000_000u128;
+        let msg_value = 2_000_000_000_000_000_000u128; // 2 ETH in wei
+        let data = make_relay_instruction_gas(gas_limit, msg_value);
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Ok((gas_limit, msg_value)));
+    }
+
+    #[test]
+    fn test_roundtrip_dropoff() {
+        let drop_off = 500_000_000_000_000_000u128; // 0.5 ETH in wei
+        let recipient = [0x42; 32];
+        let data = make_relay_instruction_gas_drop_off(drop_off, &recipient);
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Ok((0, drop_off)));
+    }
+
+    #[test]
+    fn test_roundtrip_builder() {
+        let gas_limit = 300_000u128;
+        let gas_msg_value = 100_000_000_000_000_000u128; // 0.1 ETH
+        let drop_off = 250_000_000_000_000_000u128; // 0.25 ETH
+        let recipient = [0x99; 32];
+
+        let data = RelayInstructionsBuilder::new()
+            .with_gas(gas_limit, gas_msg_value)
+            .with_gas_drop_off(drop_off, &recipient)
+            .build();
+
+        let result = parse_relay_instructions(&data);
+        assert_eq!(result, Ok((gas_limit, gas_msg_value + drop_off)));
+    }
 }

svm/modules/executor-requests/src/lib.rs

@@ -1,24 +1,33 @@
 # Pinocchio Programs
 
-This directory contains Solana programs built with the Pinocchio framework for the executor quoter system.
+Solana programs for the executor quoter system.
+
+## Overview
+
+- **executor-quoter-router** - Defines the quoter interface specification and routes CPI calls to registered quoter implementations. See [programs/executor-quoter-router/README.md](programs/executor-quoter-router/README.md).
+- **executor-quoter** - Example quoter implementation. Integrators can use this as a reference or build their own. See [programs/executor-quoter/README.md](programs/executor-quoter/README.md).
+
+These programs use the [Pinocchio](https://github.com/febo/pinocchio) framework, but quoter implementations are framework-agnostic. Any program adhering to the CPI interface defined by the router will work.
 
 ## Directory Structure
 
-- `programs/executor-quoter/` - Quoter program for price quotes
-- `programs/executor-quoter-router/` - Router program for quoter registration and execution routing
+- `programs/executor-quoter/` - Example quoter implementation
+- `programs/executor-quoter-router/` - Router program defining the quoter spec
 - `tests/executor-quoter-tests/` - Integration tests and benchmarks for executor-quoter
 - `tests/executor-quoter-router-tests/` - Integration tests and benchmarks for executor-quoter-router
 
 ## Prerequisites
 
 - Solana CLI v1.18.17 or later
-- A keypair file for the quoter updater address
 
-Generate a test keypair if you don't have one:
+### Testing Prerequisites
+
+Generate test keypairs before building or running tests:
 
 ```bash
 mkdir -p ../test-keys
 solana-keygen new --no-bip39-passphrase -o ../test-keys/quoter-updater.json
+solana-keygen new --no-bip39-passphrase -o ../test-keys/quoter-payee.json
 ```
 
 ## Building
@@ -72,11 +81,13 @@ export SBF_OUT_DIR=$(pwd)/target/deploy
 # Run unit tests (pure Rust math module)
 cargo test -p executor-quoter
 
-# Run integration tests (uses mollusk-svm to simulate program execution)
-cargo test -p executor-quoter-tests -p executor-quoter-router-tests
+# Run integration tests (uses solana-program-test to simulate program execution)
+cargo test -p executor-quoter-tests -p executor-quoter-router-tests -- --test-threads=1
 ```
 
-Note: These tests use native `cargo test`, not `cargo test-sbf`. The unit tests are pure Rust without SBF dependencies. The integration tests use mollusk-svm which loads the pre-built `.so` files and simulates program execution natively.
+Note: These tests use native `cargo test`, not `cargo test-sbf`. The unit tests are pure Rust without SBF dependencies. The integration tests use solana-program-test which loads the pre-built `.so` files and simulates program execution natively.
+
+The `--test-threads=1` flag is required because `solana-program-test` can exhibit race conditions when multiple tests load BPF programs in parallel. Running tests sequentially avoids these issues.
 
 ## Running Benchmarks
 
@@ -92,6 +103,6 @@ cargo bench -p executor-quoter-router-tests
 
 ## Notes
 
-- The test crates use `solana-program-test` and [mollusk-svm](https://github.com/buffalojoec/mollusk) to load and execute the compiled `.so` files in a simulated SVM environment.
+- The test crates use `solana-program-test` to load and execute the compiled `.so` files in a simulated SVM environment. Benchmarks use [mollusk-svm](https://github.com/buffalojoec/mollusk) for compute unit measurements.
 - Tests will fail if the `.so` files are not built first.
 - The `QUOTER_UPDATER_PUBKEY` is baked into the program at compile time and cannot be changed without rebuilding.

svm/pinocchio/Cargo.lock

@@ -0,0 +1,42 @@
+# Executor Quoter Router
+
+Router program that dispatches quote requests and execution requests to registered quoter implementations.
+
+## Overview
+
+The router manages quoter registrations and routes CPI calls to the appropriate quoter program. It defines the interface that quoter implementations must adhere to.
+
+## Instructions
+
+**UpdateQuoterContract (discriminator: 0)**
+- Registers or updates a quoter's implementation mapping
+- Accounts: `[payer, sender, config, quoter_registration, system_program]`
+
+**QuoteExecution (discriminator: 1)**
+- Gets a quote from a registered quoter via CPI
+- Accounts: `[quoter_registration, quoter_program, config, chain_info, quote_body]`
+- CPI to quoter's `RequestQuote` instruction (discriminator: `[2, 0, 0, 0, 0, 0, 0, 0]`)
+
+**RequestExecution (discriminator: 2)**
+- Executes cross-chain request through the router
+- Accounts: `[payer, config, quoter_registration, quoter_program, executor_program, payee, refund_addr, system_program, quoter_config, chain_info, quote_body, event_cpi]`
+- CPI to quoter's `RequestExecutionQuote` instruction (discriminator: `[3, 0, 0, 0, 0, 0, 0, 0]`)
+
+## Quoter Interface Requirements
+
+Quoter implementations must support the following CPI interface:
+
+### RequestQuote
+- Discriminator: 8 bytes (`[2, 0, 0, 0, 0, 0, 0, 0]`)
+- Accounts: `[config, chain_info, quote_body]`
+- Returns: `u64` (big endian) payment amount via `set_return_data`
+
+### RequestExecutionQuote
+- Discriminator: 8 bytes (`[3, 0, 0, 0, 0, 0, 0, 0]`)
+- Accounts: `[config, chain_info, quote_body, event_cpi]`
+- Returns: 72 bytes via `set_return_data`:
+  - bytes 0-7: `u64` required payment (big-endian)
+  - bytes 8-39: 32-byte payee address
+  - bytes 40-71: 32-byte quote body (EQ01 format)
+
+See `executor-quoter` for a reference implementation.

svm/pinocchio/README.md

@@ -53,7 +53,6 @@ pub fn make_signed_quote_eq02(
 /// - bytes 130-161: signature_s (32 bytes)
 /// - byte 162:     signature_v (1 byte)
 #[derive(Debug, Clone, Copy)]
-#[allow(dead_code)]
 pub struct GovernanceMessage {
     pub chain_id: u16,
     pub quoter_address: [u8; 20],