fuel_vm/interpreter/
flow.rs

1use crate::{
2    call::{
3        Call,
4        CallFrame,
5    },
6    constraints::reg_key::*,
7    consts::*,
8    context::Context,
9    error::{
10        IoResult,
11        RuntimeError,
12        SimpleResult,
13    },
14    interpreter::{
15        contract::{
16            balance_decrease,
17            balance_increase,
18            contract_size,
19        },
20        gas::{
21            dependent_gas_charge_without_base,
22            gas_charge,
23        },
24        internal::{
25            current_contract,
26            external_asset_id_balance_sub,
27            inc_pc,
28            internal_contract,
29            set_frame_pointer,
30        },
31        receipts::ReceiptsCtx,
32        ExecutableTransaction,
33        Interpreter,
34        Memory,
35        MemoryInstance,
36        PanicContext,
37        RuntimeBalances,
38    },
39    prelude::{
40        Bug,
41        BugVariant,
42    },
43    storage::{
44        ContractsRawCode,
45        InterpreterStorage,
46    },
47    verification::Verifier,
48};
49use alloc::{
50    collections::BTreeSet,
51    vec::Vec,
52};
53use core::cmp;
54use fuel_asm::{
55    Instruction,
56    PanicInstruction,
57    RegId,
58};
59use fuel_storage::{
60    StorageAsRef,
61    StorageRead,
62    StorageSize,
63};
64use fuel_tx::{
65    DependentCost,
66    PanicReason,
67    Receipt,
68};
69use fuel_types::{
70    bytes::padded_len_usize,
71    canonical::Serialize,
72    AssetId,
73    Bytes32,
74    ContractId,
75    Word,
76};
77
78#[cfg(test)]
79mod jump_tests;
80#[cfg(test)]
81mod ret_tests;
82#[cfg(test)]
83mod tests;
84
85impl<M, S, Tx, Ecal, V> Interpreter<M, S, Tx, Ecal, V>
86where
87    M: Memory,
88    Tx: ExecutableTransaction,
89{
90    pub(crate) fn jump(&mut self, args: JumpArgs) -> SimpleResult<()> {
91        let (SystemRegisters { pc, is, .. }, _) = split_registers(&mut self.registers);
92        args.jump(is.as_ref(), pc)
93    }
94
95    pub(crate) fn ret(&mut self, a: Word) -> SimpleResult<()> {
96        let current_contract =
97            current_contract(&self.context, self.registers.fp(), self.memory.as_ref())?;
98        let input = RetCtx {
99            receipts: &mut self.receipts,
100            frames: &mut self.frames,
101            registers: &mut self.registers,
102            memory: self.memory.as_ref(),
103            context: &mut self.context,
104            current_contract,
105        };
106        input.ret(a)
107    }
108
109    pub(crate) fn ret_data(&mut self, a: Word, b: Word) -> SimpleResult<Bytes32> {
110        let current_contract =
111            current_contract(&self.context, self.registers.fp(), self.memory.as_ref())?;
112        let input = RetCtx {
113            frames: &mut self.frames,
114            registers: &mut self.registers,
115            memory: self.memory.as_mut(),
116            receipts: &mut self.receipts,
117            context: &mut self.context,
118            current_contract,
119        };
120        input.ret_data(a, b)
121    }
122
123    pub(crate) fn revert(&mut self, a: Word) -> SimpleResult<()> {
124        let current_contract =
125            current_contract(&self.context, self.registers.fp(), self.memory.as_ref())
126                .unwrap_or(Some(ContractId::zeroed()));
127        revert(
128            &mut self.receipts,
129            current_contract,
130            self.registers.pc(),
131            self.registers.is(),
132            a,
133        )
134    }
135
136    pub(crate) fn append_panic_receipt(&mut self, result: PanicInstruction) {
137        let pc = self.registers[RegId::PC];
138        let is = self.registers[RegId::IS];
139
140        let mut receipt =
141            Receipt::panic(self.internal_contract().unwrap_or_default(), result, pc, is);
142
143        match self.panic_context {
144            PanicContext::None => {}
145            PanicContext::ContractId(contract_id) => {
146                receipt = receipt.with_panic_contract_id(Some(contract_id));
147            }
148        };
149        self.panic_context = PanicContext::None;
150
151        self.receipts
152            .push(receipt)
153            .expect("Appending a panic receipt cannot fail");
154    }
155}
156
157struct RetCtx<'vm> {
158    frames: &'vm mut Vec<CallFrame>,
159    registers: &'vm mut [Word; VM_REGISTER_COUNT],
160    memory: &'vm MemoryInstance,
161    receipts: &'vm mut ReceiptsCtx,
162    context: &'vm mut Context,
163    current_contract: Option<ContractId>,
164}
165
166impl RetCtx<'_> {
167    pub(crate) fn ret(self, a: Word) -> SimpleResult<()> {
168        let receipt = Receipt::ret(
169            self.current_contract.unwrap_or_else(ContractId::zeroed),
170            a,
171            self.registers[RegId::PC],
172            self.registers[RegId::IS],
173        );
174
175        self.registers[RegId::RET] = a;
176        self.registers[RegId::RETL] = 0;
177
178        // TODO if ret instruction is in memory boundary, inc_pc shouldn't fail
179        self.return_from_context(receipt)
180    }
181
182    pub(crate) fn return_from_context(mut self, receipt: Receipt) -> SimpleResult<()> {
183        if let Some(frame) = self.frames.pop() {
184            let registers = &mut self.registers;
185            let context = &mut self.context;
186
187            registers[RegId::CGAS] = registers[RegId::CGAS]
188                .checked_add(frame.context_gas())
189                .ok_or_else(|| Bug::new(BugVariant::ContextGasOverflow))?;
190
191            let cgas = registers[RegId::CGAS];
192            let ggas = registers[RegId::GGAS];
193            let ret = registers[RegId::RET];
194            let retl = registers[RegId::RETL];
195            let hp = registers[RegId::HP];
196
197            registers.copy_from_slice(frame.registers());
198
199            registers[RegId::CGAS] = cgas;
200            registers[RegId::GGAS] = ggas;
201            registers[RegId::RET] = ret;
202            registers[RegId::RETL] = retl;
203            registers[RegId::HP] = hp;
204
205            let fp = registers[RegId::FP];
206            set_frame_pointer(context, registers.fp_mut(), fp);
207        }
208
209        self.receipts.push(receipt)?;
210
211        Ok(inc_pc(self.registers.pc_mut())?)
212    }
213
214    pub(crate) fn ret_data(self, a: Word, b: Word) -> SimpleResult<Bytes32> {
215        let data = self.memory.read(a, b)?.to_vec();
216
217        let receipt = Receipt::return_data(
218            self.current_contract.unwrap_or_else(ContractId::zeroed),
219            a,
220            self.registers[RegId::PC],
221            self.registers[RegId::IS],
222            data,
223        );
224        let digest = *receipt
225            .digest()
226            .expect("Receipt is created above and `digest` should exist");
227
228        self.registers[RegId::RET] = a;
229        self.registers[RegId::RETL] = b;
230
231        self.return_from_context(receipt)?;
232
233        Ok(digest)
234    }
235}
236
237pub(crate) fn revert(
238    receipts: &mut ReceiptsCtx,
239    current_contract: Option<ContractId>,
240    pc: Reg<PC>,
241    is: Reg<IS>,
242    a: Word,
243) -> SimpleResult<()> {
244    let receipt = Receipt::revert(
245        current_contract.unwrap_or_else(ContractId::zeroed),
246        a,
247        *pc,
248        *is,
249    );
250
251    receipts.push(receipt)
252}
253
254#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
255pub enum JumpMode {
256    /// `$pc = $is + address`
257    Absolute,
258    /// `$pc = $pc + address`
259    RelativeForwards,
260    /// `$pc = $pc - address`
261    RelativeBackwards,
262}
263
264#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
265pub struct JumpArgs {
266    /// Condition. The jump is performed only if this is true.
267    condition: bool,
268    /// The kind of jump performed
269    mode: JumpMode,
270    /// Dynamic part of the jump target, i.e. register value
271    dynamic: Word,
272    /// Fixed part of the jump target, i.e. immediate value
273    fixed: Word,
274}
275
276impl JumpArgs {
277    pub(crate) fn new(mode: JumpMode) -> Self {
278        Self {
279            condition: true,
280            mode,
281            dynamic: 0,
282            fixed: 0,
283        }
284    }
285
286    pub(crate) fn with_condition(mut self, condition: bool) -> Self {
287        self.condition = condition;
288        self
289    }
290
291    pub(crate) fn to_address(mut self, addr: Word) -> Self {
292        self.dynamic = addr;
293        self
294    }
295
296    pub(crate) fn plus_fixed(mut self, addr: Word) -> Self {
297        self.fixed = addr;
298        self
299    }
300
301    pub(crate) fn jump(&self, is: Reg<IS>, mut pc: RegMut<PC>) -> SimpleResult<()> {
302        if !self.condition {
303            return Ok(inc_pc(pc)?)
304        }
305
306        let offset_instructions = match self.mode {
307            JumpMode::Absolute => self.dynamic.saturating_add(self.fixed),
308            // Here +1 is added since jumping to the jump instruction itself doesn't make
309            // sense
310            JumpMode::RelativeForwards | JumpMode::RelativeBackwards => {
311                self.dynamic.saturating_add(self.fixed).saturating_add(1)
312            }
313        };
314
315        let offset_bytes = offset_instructions.saturating_mul(Instruction::SIZE as Word);
316
317        let target_addr = match self.mode {
318            JumpMode::Absolute => is.saturating_add(offset_bytes),
319            JumpMode::RelativeForwards => pc.saturating_add(offset_bytes),
320            JumpMode::RelativeBackwards => pc
321                .checked_sub(offset_bytes)
322                .ok_or(PanicReason::MemoryOverflow)?,
323        };
324
325        if target_addr >= VM_MAX_RAM {
326            return Err(PanicReason::MemoryOverflow.into())
327        }
328
329        *pc = target_addr;
330        Ok(())
331    }
332}
333
334impl<M, S, Tx, Ecal, V> Interpreter<M, S, Tx, Ecal, V>
335where
336    M: Memory,
337    S: InterpreterStorage,
338    Tx: ExecutableTransaction,
339    V: Verifier,
340{
341    /// Prepare a call instruction for execution
342    pub fn prepare_call(
343        &mut self,
344        ra: RegId,
345        rb: RegId,
346        rc: RegId,
347        rd: RegId,
348    ) -> IoResult<(), S::DataError> {
349        self.prepare_call_inner(
350            self.registers[ra],
351            self.registers[rb],
352            self.registers[rc],
353            self.registers[rd],
354        )
355    }
356
357    /// Prepare a call instruction for execution
358    fn prepare_call_inner(
359        &mut self,
360        call_params_pointer: Word,
361        amount_of_coins_to_forward: Word,
362        asset_id_pointer: Word,
363        amount_of_gas_to_forward: Word,
364    ) -> IoResult<(), S::DataError> {
365        let params = PrepareCallParams {
366            call_params_pointer,
367            asset_id_pointer,
368            amount_of_coins_to_forward,
369            amount_of_gas_to_forward,
370        };
371        let gas_cost = self.gas_costs().call();
372        let new_storage_gas_per_byte = self.gas_costs().new_storage_per_byte();
373        // Charge only for the `base` execution.
374        // We will charge for the frame size in the `prepare_call`.
375        self.gas_charge(gas_cost.base())?;
376        let current_contract =
377            current_contract(&self.context, self.registers.fp(), self.memory.as_ref())?;
378
379        PrepareCallCtx {
380            params,
381            registers: (&mut self.registers).into(),
382            memory: self.memory.as_mut(),
383            context: &mut self.context,
384            gas_cost,
385            runtime_balances: &mut self.balances,
386            storage: &mut self.storage,
387            input_contracts: &self.input_contracts,
388            panic_context: &mut self.panic_context,
389            new_storage_gas_per_byte,
390            receipts: &mut self.receipts,
391            frames: &mut self.frames,
392            current_contract,
393            verifier: &mut self.verifier,
394        }
395        .prepare_call()
396    }
397}
398
399#[cfg_attr(test, derive(Default))]
400struct PrepareCallParams {
401    /// Register A of input
402    pub call_params_pointer: Word,
403    /// Register B of input
404    pub amount_of_coins_to_forward: Word,
405    /// Register C of input
406    pub asset_id_pointer: Word,
407    /// Register D of input
408    pub amount_of_gas_to_forward: Word,
409}
410
411struct PrepareCallSystemRegisters<'a> {
412    hp: Reg<'a, HP>,
413    sp: RegMut<'a, SP>,
414    ssp: RegMut<'a, SSP>,
415    fp: RegMut<'a, FP>,
416    pc: RegMut<'a, PC>,
417    is: RegMut<'a, IS>,
418    bal: RegMut<'a, BAL>,
419    cgas: RegMut<'a, CGAS>,
420    ggas: RegMut<'a, GGAS>,
421    flag: RegMut<'a, FLAG>,
422}
423
424struct PrepareCallRegisters<'a> {
425    system_registers: PrepareCallSystemRegisters<'a>,
426    program_registers: ProgramRegistersRef<'a>,
427    unused_registers: PrepareCallUnusedRegisters<'a>,
428}
429
430struct PrepareCallUnusedRegisters<'a> {
431    zero: Reg<'a, ZERO>,
432    one: Reg<'a, ONE>,
433    of: Reg<'a, OF>,
434    err: Reg<'a, ERR>,
435    ret: Reg<'a, RET>,
436    retl: Reg<'a, RETL>,
437}
438
439impl PrepareCallRegisters<'_> {
440    fn copy_registers(&self) -> [Word; VM_REGISTER_COUNT] {
441        copy_registers(&self.into(), &self.program_registers)
442    }
443}
444
445struct PrepareCallCtx<'vm, S, V> {
446    params: PrepareCallParams,
447    registers: PrepareCallRegisters<'vm>,
448    memory: &'vm mut MemoryInstance,
449    context: &'vm mut Context,
450    gas_cost: DependentCost,
451    runtime_balances: &'vm mut RuntimeBalances,
452    new_storage_gas_per_byte: Word,
453    storage: &'vm mut S,
454    input_contracts: &'vm BTreeSet<ContractId>,
455    panic_context: &'vm mut PanicContext,
456    receipts: &'vm mut ReceiptsCtx,
457    frames: &'vm mut Vec<CallFrame>,
458    current_contract: Option<ContractId>,
459    verifier: &'vm mut V,
460}
461
462impl<S, V> PrepareCallCtx<'_, S, V> {
463    fn prepare_call(mut self) -> IoResult<(), S::DataError>
464    where
465        S: InterpreterStorage,
466        V: Verifier,
467    {
468        let call_bytes = self
469            .memory
470            .read(self.params.call_params_pointer, Call::LEN)?;
471        let call = Call::try_from(call_bytes)?;
472        let asset_id =
473            AssetId::new(self.memory.read_bytes(self.params.asset_id_pointer)?);
474
475        let code_size = contract_size(&self.storage, call.to())? as usize;
476        let code_size_padded =
477            padded_len_usize(code_size).ok_or(PanicReason::MemoryOverflow)?;
478
479        let total_size_in_stack = CallFrame::serialized_size()
480            .checked_add(code_size_padded)
481            .ok_or_else(|| Bug::new(BugVariant::CodeSizeOverflow))?;
482
483        dependent_gas_charge_without_base(
484            self.registers.system_registers.cgas.as_mut(),
485            self.registers.system_registers.ggas.as_mut(),
486            self.gas_cost,
487            code_size_padded as Word,
488        )?;
489
490        if let Some(source_contract) = self.current_contract {
491            balance_decrease(
492                self.storage,
493                &source_contract,
494                &asset_id,
495                self.params.amount_of_coins_to_forward,
496            )?;
497        } else {
498            let amount = self.params.amount_of_coins_to_forward;
499            external_asset_id_balance_sub(
500                self.runtime_balances,
501                self.memory,
502                &asset_id,
503                amount,
504            )?;
505        }
506
507        self.verifier.check_contract_in_inputs(
508            self.panic_context,
509            self.input_contracts,
510            call.to(),
511        )?;
512
513        // credit contract asset_id balance
514        let (_, created_new_entry) = balance_increase(
515            self.storage,
516            call.to(),
517            &asset_id,
518            self.params.amount_of_coins_to_forward,
519        )?;
520
521        if created_new_entry {
522            // If a new entry was created, we must charge gas for it
523            gas_charge(
524                self.registers.system_registers.cgas.as_mut(),
525                self.registers.system_registers.ggas.as_mut(),
526                ((Bytes32::LEN + WORD_SIZE) as u64)
527                    .saturating_mul(self.new_storage_gas_per_byte),
528            )?;
529        }
530
531        let forward_gas_amount = cmp::min(
532            *self.registers.system_registers.cgas,
533            self.params.amount_of_gas_to_forward,
534        );
535
536        // subtract gas
537        *self.registers.system_registers.cgas = (*self.registers.system_registers.cgas)
538            .checked_sub(forward_gas_amount)
539            .ok_or_else(|| Bug::new(BugVariant::ContextGasUnderflow))?;
540
541        // Construct frame
542        let mut frame = CallFrame::new(
543            *call.to(),
544            asset_id,
545            self.registers.copy_registers(),
546            code_size_padded,
547            call.a(),
548            call.b(),
549        )
550        .ok_or(PanicReason::MemoryOverflow)?;
551        *frame.context_gas_mut() = *self.registers.system_registers.cgas;
552        *frame.global_gas_mut() = *self.registers.system_registers.ggas;
553
554        // Allocate stack memory
555        let old_sp = *self.registers.system_registers.sp;
556        let new_sp = old_sp.saturating_add(total_size_in_stack as Word);
557        self.memory.grow_stack(new_sp)?;
558        *self.registers.system_registers.sp = new_sp;
559        *self.registers.system_registers.ssp = new_sp;
560
561        let id = internal_contract(
562            self.context,
563            self.registers.system_registers.fp.as_ref(),
564            self.memory,
565        )
566        .unwrap_or_default();
567
568        set_frame_pointer(
569            self.context,
570            self.registers.system_registers.fp.as_mut(),
571            old_sp,
572        );
573
574        // Write the frame to memory
575        // Ownership checks are disabled because we just allocated the memory above.
576        let dst = self.memory.write_noownerchecks(
577            *self.registers.system_registers.fp,
578            total_size_in_stack,
579        )?;
580        let (mem_frame, mem_code) = dst.split_at_mut(CallFrame::serialized_size());
581        mem_frame.copy_from_slice(&frame.to_bytes());
582        let (mem_code, mem_code_padding) = mem_code.split_at_mut(code_size);
583        read_contract(call.to(), self.storage, mem_code)?;
584        mem_code_padding.fill(0);
585
586        #[allow(clippy::arithmetic_side_effects)] // Checked above
587        let code_start =
588            (*self.registers.system_registers.fp) + CallFrame::serialized_size() as Word;
589
590        *self.registers.system_registers.pc = code_start;
591        *self.registers.system_registers.bal = self.params.amount_of_coins_to_forward;
592        *self.registers.system_registers.is = *self.registers.system_registers.pc;
593        *self.registers.system_registers.cgas = forward_gas_amount;
594        *self.registers.system_registers.flag = 0;
595
596        let receipt = Receipt::call(
597            id,
598            *call.to(),
599            self.params.amount_of_coins_to_forward,
600            asset_id,
601            forward_gas_amount,
602            call.a(),
603            call.b(),
604            *self.registers.system_registers.pc,
605            *self.registers.system_registers.is,
606        );
607
608        self.receipts.push(receipt)?;
609
610        self.frames.push(frame);
611
612        Ok(())
613    }
614}
615
616fn read_contract<S>(
617    contract: &ContractId,
618    storage: &S,
619    dst: &mut [u8],
620) -> IoResult<(), S::Error>
621where
622    S: StorageSize<ContractsRawCode> + StorageRead<ContractsRawCode> + StorageAsRef,
623{
624    if !storage
625        .storage::<ContractsRawCode>()
626        .read(contract, 0, dst)
627        .map_err(RuntimeError::Storage)?
628    {
629        return Err(PanicReason::ContractNotFound.into());
630    }
631    Ok(())
632}
633
634impl<'a> From<&'a PrepareCallRegisters<'_>> for SystemRegistersRef<'a> {
635    fn from(registers: &'a PrepareCallRegisters) -> Self {
636        Self {
637            hp: registers.system_registers.hp,
638            sp: registers.system_registers.sp.as_ref(),
639            ssp: registers.system_registers.ssp.as_ref(),
640            fp: registers.system_registers.fp.as_ref(),
641            pc: registers.system_registers.pc.as_ref(),
642            is: registers.system_registers.is.as_ref(),
643            bal: registers.system_registers.bal.as_ref(),
644            cgas: registers.system_registers.cgas.as_ref(),
645            ggas: registers.system_registers.ggas.as_ref(),
646            flag: registers.system_registers.flag.as_ref(),
647            zero: registers.unused_registers.zero,
648            one: registers.unused_registers.one,
649            of: registers.unused_registers.of,
650            err: registers.unused_registers.err,
651            ret: registers.unused_registers.ret,
652            retl: registers.unused_registers.retl,
653        }
654    }
655}
656
657impl<'reg> From<&'reg mut [Word; VM_REGISTER_COUNT]> for PrepareCallRegisters<'reg> {
658    fn from(registers: &'reg mut [Word; VM_REGISTER_COUNT]) -> Self {
659        let (r, w) = split_registers(registers);
660        let (r, u) = r.into();
661        Self {
662            system_registers: r,
663            program_registers: w.into(),
664            unused_registers: u,
665        }
666    }
667}
668
669impl<'reg> From<SystemRegisters<'reg>>
670    for (
671        PrepareCallSystemRegisters<'reg>,
672        PrepareCallUnusedRegisters<'reg>,
673    )
674{
675    fn from(registers: SystemRegisters<'reg>) -> Self {
676        let read = PrepareCallSystemRegisters {
677            hp: registers.hp.into(),
678            sp: registers.sp,
679            ssp: registers.ssp,
680            fp: registers.fp,
681            pc: registers.pc,
682            is: registers.is,
683            bal: registers.bal,
684            cgas: registers.cgas,
685            ggas: registers.ggas,
686            flag: registers.flag,
687        };
688
689        (
690            read,
691            PrepareCallUnusedRegisters {
692                zero: registers.zero.into(),
693                one: registers.one.into(),
694                of: registers.of.into(),
695                err: registers.err.into(),
696                ret: registers.ret.into(),
697                retl: registers.retl.into(),
698            },
699        )
700    }
701}
fuel_vm/interpreter/flow.rs

fuel_vm/interpreter/
flow.rs
