stwo-cairo-adapter 1.2.2

Adapter for converting Cairo VM execution traces to Stwo prover format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

use stwo::core::fields::m31::M31;

#[derive(Clone, Debug)]
pub enum OpcodeExtension {
    Stone,
    Blake,
    BlakeFinalize,
    QM31Operation,
}
impl OpcodeExtension {
    /// Converts the trailing bits (encoded_instr after shifting right by 63) of an instruction to
    /// an OpcodeExtension and returns it.
    /// # Panics
    /// - if the trailing bits do not correspond to a valid OpcodeExtension.
    pub fn from_instruction_trailing_bits(value: u128) -> OpcodeExtension {
        match value {
            0 => OpcodeExtension::Stone,
            1 => OpcodeExtension::Blake,
            2 => OpcodeExtension::BlakeFinalize,
            3 => OpcodeExtension::QM31Operation,
            _ => panic!("Invalid opcode extension number: {value}"),
        }
    }
}

#[derive(Clone, Debug)]
pub struct Instruction {
    pub offset0: i16,
    pub offset1: i16,
    pub offset2: i16,
    pub dst_base_fp: bool,
    pub op0_base_fp: bool,
    pub op_1_imm: bool,
    pub op_1_base_fp: bool,
    pub op_1_base_ap: bool,
    pub res_add: bool,
    pub res_mul: bool,
    pub pc_update_jump: bool,
    pub pc_update_jump_rel: bool,
    pub pc_update_jnz: bool,
    pub ap_update_add: bool,
    pub ap_update_add_1: bool,
    pub opcode_call: bool,
    pub opcode_ret: bool,
    pub opcode_assert_eq: bool,
    pub opcode_extension: OpcodeExtension,
}
impl Instruction {
    pub fn decode(mut encoded_instr: u128) -> Instruction {
        let mut next_offset = || {
            let offset = (encoded_instr & 0xffff) as u16;
            encoded_instr >>= 16;
            offset.overflowing_sub(0x8000u16).0 as i16
        };
        let offset0 = next_offset();
        let offset1 = next_offset();
        let offset2 = next_offset();

        let mut next_bit = || {
            let bit = encoded_instr & 1;
            encoded_instr >>= 1;
            bit != 0
        };

        Instruction {
            offset0,
            offset1,
            offset2,
            dst_base_fp: next_bit(),
            op0_base_fp: next_bit(),
            op_1_imm: next_bit(),
            op_1_base_fp: next_bit(),
            op_1_base_ap: next_bit(),
            res_add: next_bit(),
            res_mul: next_bit(),
            pc_update_jump: next_bit(),
            pc_update_jump_rel: next_bit(),
            pc_update_jnz: next_bit(),
            ap_update_add: next_bit(),
            ap_update_add_1: next_bit(),
            opcode_call: next_bit(),
            opcode_ret: next_bit(),
            opcode_assert_eq: next_bit(),
            // The remaining bits in encoded_instr are the opcode extension.
            opcode_extension: OpcodeExtension::from_instruction_trailing_bits(encoded_instr),
        }
    }
}

/// Constructs the input for the DecodeInstruction routine.
///
/// # Arguments
///
/// - `encoded_instr`: The encoded instruction.
///
/// # Returns
///
/// The Deconstructed instruction in the form of (offsets, flags, extension).
pub fn deconstruct_instruction(mut encoded_instr: u128) -> ([M31; 3], [M31; 2], M31) {
    let mut next_offset = || {
        let offset = (encoded_instr & 0xffff) as u16;
        encoded_instr >>= 16;
        offset
    };
    let offsets = std::array::from_fn(|_| M31(next_offset() as u32));

    let mut next_bit = || {
        let bit = (encoded_instr & 1) as u32;
        encoded_instr >>= 1;
        bit
    };

    let mut flags = [0; 2];
    for i in 0..15 {
        let bit = next_bit();
        if i < 6 {
            flags[0] |= bit << (i + 3);
        } else {
            flags[1] |= bit << (i - 6);
        }
    }
    let flags = flags.map(M31);

    // The remaining bits in encoded_instr are the opcode extension.
    let opcode_extension = M31(encoded_instr as u32);

    (offsets, flags, opcode_extension)
}

#[cfg(test)]
mod tests {
    use stwo::core::fields::m31::M31;

    use crate::decode::deconstruct_instruction;

    #[test]
    fn test_deconstruct_instruction() {
        let encoded_instr = 0b10100011010001010000000000000000100000000000000110000000000000111;
        let expected_opcode_extension = M31(2);
        let expected_flags = [0x50, 0x11a].map(M31);
        let expected_offsets = [7, 3, 1].map(M31);

        let (offsets, flags, opcode_extension) = deconstruct_instruction(encoded_instr);

        assert_eq!(offsets, expected_offsets);
        assert_eq!(flags, expected_flags);
        assert_eq!(opcode_extension, expected_opcode_extension);
    }
}