Merge pull request #196 from Dataguru-tech/feat/Implement-Emergency-Shutdown-verification-rule

feat/Implement 'Emergency Shutdown' verification rule

Author: Gbangbolaoluwagbemiga

contracts/my-contract/.github/workflows/fuzz.yml

@@ -0,0 +1,25 @@
+name: Fuzzing
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 2 * * *"
+
+jobs:
+  bolero-fuzz:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - run: cargo install cargo-bolero
+      - run: cargo bolero test fuzz_raw_bytes_no_panic --time 60s
+      - run: cargo bolero test fuzz_structured_message_no_panic --time 60s
+
+  cargo-fuzz:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - run: cargo install cargo-fuzz
+      - run: cargo fuzz run fuzz_cross_contract -- -max_total_time=120

contracts/my-contract/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "my-contract"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+borsh = "1.3"
+
+[dev-dependencies]
+bolero = "0.10"
+bolero-generator = "0.10"

contracts/my-contract/fuzz/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "my-contract-fuzz"
+version = "0.0.1"
+edition = "2021"
+publish = false
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+my-contract = { path = ".." }
+borsh = "1.3"
+arbitrary = { version = "1", features = ["derive"] }
+
+[[bin]]
+name = "fuzz_cross_contract"
+path = "fuzz_targets/fuzz_cross_contract.rs"
+test = false
+doc = false

contracts/my-contract/fuzz/fuzz_targets/fuzz_cross_contract.rs

@@ -0,0 +1,8 @@
+#![no_main]
+
+use libfuzzer_sys::fuzz_target;
+use my_contract::handle_cross_contract_message;
+
+fuzz_target!(|data: &[u8]| {
+    let _ = handle_cross_contract_message(data);
+});

contracts/my-contract/src/lib.rs

@@ -0,0 +1,50 @@
+use borsh::{BorshDeserialize, BorshSerialize};
+
+#[derive(Debug, BorshSerialize, BorshDeserialize, Clone)]
+pub struct CrossContractMessage {
+    pub sender: [u8; 32],
+    pub method_id: u8,
+    pub payload: Vec<u8>,
+    pub nonce: u64,
+}
+
+#[derive(Debug, PartialEq)]
+pub enum ContractError {
+    DeserializationFailed,
+    UnknownMethod,
+    InvalidPayload(String),
+    OverflowDetected,
+}
+
+pub fn handle_cross_contract_message(raw: &[u8]) -> Result<String, ContractError> {
+    let msg = CrossContractMessage::try_from_slice(raw)
+        .map_err(|_| ContractError::DeserializationFailed)?;
+    match msg.method_id {
+        0 => handle_transfer(&msg.payload),
+        1 => handle_query(&msg.payload),
+        2 => handle_callback(&msg.payload),
+        _ => Err(ContractError::UnknownMethod),
+    }
+}
+
+fn handle_transfer(payload: &[u8]) -> Result<String, ContractError> {
+    if payload.len() < 8 {
+        return Err(ContractError::InvalidPayload("too short".into()));
+    }
+    let amount = u64::from_le_bytes(payload[0..8].try_into().unwrap());
+    let fee = amount.checked_mul(3).ok_or(ContractError::OverflowDetected)?;
+    Ok(format!("transfer: amount={amount}, fee={fee}"))
+}
+
+fn handle_query(payload: &[u8]) -> Result<String, ContractError> {
+    let key = std::str::from_utf8(payload)
+        .map_err(|_| ContractError::InvalidPayload("invalid utf8".into()))?;
+    Ok(format!("query: key={key}"))
+}
+
+fn handle_callback(payload: &[u8]) -> Result<String, ContractError> {
+    if payload.is_empty() {
+        return Err(ContractError::InvalidPayload("empty callback".into()));
+    }
+    Ok(format!("callback: {} bytes", payload.len()))
+}

contracts/my-contract/tests/bolero_fuzz.rs

@@ -0,0 +1,48 @@
+use bolero::{check, generator::*};
+use borsh::BorshSerialize;
+use my_contract::{handle_cross_contract_message, CrossContractMessage};
+
+#[test]
+fn fuzz_raw_bytes_no_panic() {
+    check!()
+        .with_type::<Vec<u8>>()
+        .for_each(|data| {
+            let _ = handle_cross_contract_message(data);
+        });
+}
+
+#[test]
+fn fuzz_structured_message_no_panic() {
+    check!()
+        .with_generator(gen::<(u8, Vec<u8>, u64)>())
+        .for_each(|(method_id, payload, nonce)| {
+            let msg = CrossContractMessage {
+                sender: [0u8; 32],
+                method_id: *method_id,
+                payload: payload.clone(),
+                nonce: *nonce,
+            };
+            if let Ok(encoded) = borsh::to_vec(&msg) {
+                let _ = handle_cross_contract_message(&encoded);
+            }
+        });
+}
+
+#[test]
+fn fuzz_truncated_messages() {
+    check!()
+        .with_type::<Vec<u8>>()
+        .with_max_len(16)
+        .for_each(|data| {
+            let _ = handle_cross_contract_message(data);
+        });
+}
+
+#[test]
+fn fuzz_oversized_payload_no_oom() {
+    check!()
+        .with_generator(gen::<Vec<u8>>().with().len(0usize..=1_000_000))
+        .for_each(|data| {
+            let _ = handle_cross_contract_message(data);
+        });
+}

my-contract/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "my-contract"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+borsh = "1.3"
+
+[dev-dependencies]
+bolero = "0.10"
+bolero-generator = "0.10"

my-contract/src/circuit_breaker.rs

@@ -0,0 +1,29 @@
+use crate::{
+    guards::{require_admin, require_active, GuardError},
+    state::{ContractState, ShutdownState},
+};
+
+pub fn pause(state: &mut ContractState, caller: &[u8; 32]) -> Result<(), GuardError> {
+    require_admin(state, caller)?;
+    require_active(state)?;
+    state.shutdown = ShutdownState::Paused;
+    Ok(())
+}
+
+pub fn emergency_shutdown(
+    state: &mut ContractState,
+    caller: &[u8; 32],
+) -> Result<(), GuardError> {
+    require_admin(state, caller)?;
+    state.shutdown = ShutdownState::Emergency;
+    Ok(())
+}
+
+pub fn unpause(state: &mut ContractState, caller: &[u8; 32]) -> Result<(), GuardError> {
+    require_admin(state, caller)?;
+    match state.shutdown {
+        ShutdownState::Paused    => { state.shutdown = ShutdownState::Active; Ok(()) }
+        ShutdownState::Emergency => Err(GuardError::EmergencyShutdown),
+        ShutdownState::Active    => Ok(()),
+    }
+}

my-contract/src/guards.rs

@@ -0,0 +1,42 @@
+use crate::state::{ContractState, ShutdownState};
+
+#[derive(Debug, PartialEq)]
+pub enum GuardError {
+    ContractPaused,
+    EmergencyShutdown,
+    Unauthorized,
+}
+
+impl std::fmt::Display for GuardError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            GuardError::ContractPaused    => write!(f, "Contract is paused"),
+            GuardError::EmergencyShutdown => write!(f, "Emergency shutdown is active"),
+            GuardError::Unauthorized      => write!(f, "Caller is not authorized"),
+        }
+    }
+}
+
+pub fn require_active(state: &ContractState) -> Result<(), GuardError> {
+    match state.shutdown {
+        ShutdownState::Active    => Ok(()),
+        ShutdownState::Paused    => Err(GuardError::ContractPaused),
+        ShutdownState::Emergency => Err(GuardError::EmergencyShutdown),
+    }
+}
+
+pub fn require_admin(state: &ContractState, caller: &[u8; 32]) -> Result<(), GuardError> {
+    if &state.admin == caller {
+        Ok(())
+    } else {
+        Err(GuardError::Unauthorized)
+    }
+}
+
+pub fn require_admin_and_active(
+    state: &ContractState,
+    caller: &[u8; 32],
+) -> Result<(), GuardError> {
+    require_admin(state, caller)?;
+    require_active(state)
+}

my-contract/src/lib.rs

@@ -0,0 +1,48 @@
+pub mod circuit_breaker;
+pub mod guards;
+pub mod state;
+
+use guards::{require_active, GuardError};
+use state::ContractState;
+
+pub fn deposit(
+    state: &mut ContractState,
+    _caller: &[u8; 32],
+    amount: u64,
+) -> Result<(), GuardError> {
+    require_active(state)?;
+    state.balance = state.balance.checked_add(amount)
+        .ok_or(GuardError::Unauthorized)?;
+    Ok(())
+}
+
+pub fn withdraw(
+    state: &mut ContractState,
+    _caller: &[u8; 32],
+    amount: u64,
+) -> Result<(), GuardError> {
+    require_active(state)?;
+    if state.balance < amount {
+        return Err(GuardError::Unauthorized);
+    }
+    state.balance -= amount;
+    Ok(())
+}
+
+pub fn update_data(
+    state: &mut ContractState,
+    _caller: &[u8; 32],
+    new_data: Vec<u8>,
+) -> Result<(), GuardError> {
+    require_active(state)?;
+    state.data = new_data;
+    Ok(())
+}
+
+pub fn get_balance(state: &ContractState) -> u64 {
+    state.balance
+}
+
+pub fn get_shutdown_status(state: &ContractState) -> &state::ShutdownState {
+    &state.shutdown
+}