RISC-V Syscall Interface Documentation

┌─────────────────────────┐
│  RISC-V Contract        │
│  Rust Smart Contract    │
└───────────┬─────────────┘
            │
            │ ecall instruction
            │ t0 = syscall_id
            │ a0-a6 = arguments
            ▼
┌─────────────────────────┐
│  Syscall Processing     │
│  (execution/mod.rs)     │
└───────────┬─────────────┘
            │
     ┌──────┴──────┐
     │             │
     ▼             ▼
┌─────────┐   ┌─────────────┐
│  HOST_* │   │ EVM Opcode  │
│  ops    │   │  Wrappers   │
└────┬────┘   └──────┬──────┘
     │               │
     └───────┬───────┘
             ▼
    ┌─────────────────┐
    │  Shared Memory  │
    │  0xBEC00000     │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │  EVM Host       │
    │  Environment    │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │ Blockchain State│
    └─────────────────┘

┌──────────────┐
│  EVM Host    │
└──────┬───────┘
       │ 1. Write serialized input
       ▼
┌──────────────────────┐
│  Shared Memory       │
│  0xBEC00000          │
└──────┬───────────────┘
       │ 2. ecall with input_size
       ▼
┌──────────────────────┐
│  RISC-V Contract     │
│  Read input data     │
│  Process syscall     │
└──────┬───────────────┘
       │ 3. Write serialized output
       ▼
┌──────────────────────┐
│  Shared Memory       │
│  0xBEC00000          │
└──────┬───────────────┘
       │ 4. Return output_size
       ▼
┌──────────────────────┐
│  EVM Host            │
│  Read output data    │
└──────────────────────┘

pub fn host_sstore(address: Address, index: U256, value: U256) 
    -> Option<StateLoad<SStoreResult>> {
    // Serialize input parameters
    let input_serialized = serialize_sstore_input(address, index, value);
    let input_size = input_serialized.len();
    
    // Write to shared memory
    unsafe {
        let dest = slice_from_raw_parts_mut(
            MINI_EVM_SYSCALLS_MEM_ADDR, 
            input_serialized.len()
        );
        dest.copy_from_slice(&input_serialized);
    }
    
    // Make syscall via ecall instruction
    let mut output_size;
    unsafe {
        asm!(
            "ecall",
            in("a0") input_size,
            lateout("a0") output_size,
            in("t0") mini_evm_syscalls_ids::HOST_SSTORE
        );
    }
    
    // Read result from shared memory
    let out_serialized = unsafe { 
        slice_from_raw_parts(MINI_EVM_SYSCALLS_MEM_ADDR, output_size) 
    };
    
    bincode::serde::decode_from_slice(
        out_serialized, 
        bincode::config::legacy()
    ).unwrap().0
}

pub fn balance<WIRE: InterpreterTypes, H: Host + ?Sized>(
    interpreter: &mut Interpreter<WIRE>,
    _host: &mut H,
) {
    popn_top!([], top, interpreter);
    let address = top.into_address();
    
    // Call host_balance syscall
    let Some(balance) = host_balance(address) else {
        interpreter.control.set_instruction_result(
            InstructionResult::FatalExternalError
        );
        return;
    };
    
    // Calculate gas cost based on EVM specification
    gas!(interpreter, 
        if spec_id.is_enabled_in(BERLIN) {
            warm_cold_cost(balance.is_cold)
        } else if spec_id.is_enabled_in(ISTANBUL) {
            700
        } else if spec_id.is_enabled_in(TANGERINE) {
            400
        } else {
            20
        }
    );
    
    *top = balance.data;
}

match run_result {
    Err(Exception::EnvironmentCallFromMMode) => {
        // Read syscall ID from t0 register
        let t0: u64 = emu.cpu.xregs.read(5);
        
        let Ok(syscall) = Syscall::try_from(t0 as u8) else {
            return return_revert(
                interpreter, 
                interpreter.control.gas.spent()
            );
        };
        
        match syscall {
            Syscall::Balance => {
                // Read address from registers a0-a2
                let address_1 = emu.cpu.xregs.read(10);
                let address_2 = emu.cpu.xregs.read(11);
                let address_3 = emu.cpu.xregs.read(12);
                
                let address = __3u64_to_address(
                    address_1, address_2, address_3
                );
                
                match host.balance(address) {
                    Some(state_load) => {
                        // Write result to registers a0-a3
                        let limbs = state_load.data.as_limbs();
                        emu.cpu.xregs.write(10, limbs[0]);
                        emu.cpu.xregs.write(11, limbs[1]);
                        emu.cpu.xregs.write(12, limbs[2]);
                        emu.cpu.xregs.write(13, limbs[3]);
                    }
                    _ => return return_revert(
                        interpreter, 
                        interpreter.control.gas.spent()
                    ),
                }
            }
            // ... other syscalls
        }
    }
}

Syscall Invoked
    ↓
Validate Syscall ID ──→ Invalid ──→ Revert Contract
    ↓ Valid
Execute Operation ──→ Failure ──→ FatalExternalError/Revert
    ↓ Success
Return Result

// Example: Query account balance
use hybrid_syscalls::*;
 
fn get_balance(address: Address) -> U256 {
    // This will trigger a syscall via the ecall instruction
    let balance = host_balance(address).expect("Balance query failed");
    balance.data
}

// Store a value
let key = U256::from(1);
let value = U256::from(42);
host_sstore(contract_address, key, value);
 
// Load a value
let stored_value = host_sload(contract_address, key)
    .expect("Storage load failed");

// Store temporary data (cleared at transaction end)
host_tstore(key, value);
 
// Load temporary data
let temp_value = host_tload(key);