ultrasonic/isa/instr.rs
1// UltraSONIC: transactional execution layer with capability-based memory access for zk-AluVM
2//
3// SPDX-License-Identifier: Apache-2.0
4//
5// Designed in 2019-2025 by Dr Maxim Orlovsky <orlovsky@ubideco.org>
6// Written in 2024-2025 by Dr Maxim Orlovsky <orlovsky@ubideco.org>
7//
8// Copyright (C) 2019-2024 LNP/BP Standards Association, Switzerland.
9// Copyright (C) 2024-2025 Laboratories for Ubiquitous Deterministic Computing (UBIDECO),
10// Institute for Distributed and Cognitive Systems (InDCS), Switzerland.
11// Copyright (C) 2019-2025 Dr Maxim Orlovsky.
12// All rights under the above copyrights are reserved.
13//
14// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
15// in compliance with the License. You may obtain a copy of the License at
16//
17// http://www.apache.org/licenses/LICENSE-2.0
18//
19// Unless required by applicable law or agreed to in writing, software distributed under the License
20// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
21// or implied. See the License for the specific language governing permissions and limitations under
22// the License.
23
24use aluvm::alu::SiteId;
25use aluvm::gfa::FieldInstr;
26use aluvm::isa::{CtrlInstr, ReservedInstr};
27
28/// AluVM ISA architecture id for Ultrasonic ISA extension.
29pub const ISA_ULTRASONIC: &str = "USONIC";
30
31/// Complete AluVM instruction set for the Ultrasonic virtual machine, which includes the following
32/// architectures:
33/// - Base ALU control architecture
34/// - `GFA256` (256-bit Galois-field arithmetics).
35/// - `USONIC`
36#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug, Display, From)]
37#[display(inner)]
38#[non_exhaustive]
39pub enum Instr<Id: SiteId> {
40 /// Control flow instructions (base ALU ISA)..
41 #[from]
42 Ctrl(CtrlInstr<Id>),
43
44 /// GFA256` (256-bit Galois-field arithmetics).
45 #[from]
46 Gfa(FieldInstr),
47
48 /// USONIC ISA.
49 #[from]
50 Usonic(UsonicInstr),
51
52 /// Reserved instruction for future use in core `ALU` ISAs.
53 #[from]
54 Reserved(ReservedInstr),
55}
56
57impl<Id: SiteId> From<aluvm::gfa::Instr<Id>> for Instr<Id> {
58 fn from(instr: aluvm::gfa::Instr<Id>) -> Self {
59 match instr {
60 aluvm::gfa::Instr::Ctrl(ctrl) => Self::Ctrl(ctrl),
61 aluvm::gfa::Instr::Gfa(gfa) => Self::Gfa(gfa),
62 aluvm::gfa::Instr::Reserved(resrv) => Self::Reserved(resrv),
63 _ => unreachable!(),
64 }
65 }
66}
67
68/// The instruction set uses iterator semantics and not random access semantic to correspond to the
69/// RISC type of the machine and not to add assumptions about abilities to access the operation
70/// state randomly.
71/// Operation state is always iterated, such that not a single state element can be missed (as long
72/// as the iterator runs to the end).
73#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug, Display)]
74#[display(inner)]
75#[non_exhaustive]
76pub enum UsonicInstr {
77 /// Checks whether there is a next destructible memory cell in the contract state listed in the
78 /// operation input and sets `CO` register accordingly.
79 #[display("cknxi destructible")]
80 CkNxIRo,
81
82 /// Checks whether there is a next immutable memory cell in the contract state listed in the
83 /// operation input and sets `CO` register accordingly.
84 #[display("cknxi immutable")]
85 CkNxIAo,
86
87 /// Checks whether there is a next destructible memory cell defined by the operation and sets
88 /// `CO` register accordingly.
89 #[display("cknxo destructible")]
90 CkNxORo,
91
92 /// Checks whether there is a next immutable memory cell defined by the operation and sets `CO`
93 /// register accordingly.
94 #[display("cknxo immutable")]
95 CkNxOAo,
96
97 /// Load operation witness [`StateValue`] to `EA`-`ED` registers.
98 #[display("ldw")]
99 LdW,
100
101 /// Load next [`StateValue`] from the current destructible memory cell input to `EA`-`ED`
102 /// registers.
103 ///
104 /// If the next state value is absent, sets `CO` to a failed state. Otherwise, resets `CO`.
105 #[display("ldi destructible")]
106 LdIRo,
107
108 /// Load next [`StateValue`] from the current immutable memory cell input to `EA`-`ED`
109 /// registers.
110 ///
111 /// If the next state value is absent, sets `CO` to a failed state. Otherwise, resets `CO`.
112 #[display("ldi immutable")]
113 LdIAo,
114
115 /// Load next [`StateValue`] from the current destructible memory cell output to `EA`-`ED`
116 /// registers.
117 ///
118 /// If the next state value is absent, sets `CO` to a failed state. Otherwise, resets `CO`.
119 #[display("ldo destructible")]
120 LdORo,
121
122 /// Load next [`StateValue`] from the current immutable memory cell output to `EA`-`ED`
123 /// registers.
124 ///
125 /// If the next state value is absent, sets `CO` to a failed state. Otherwise, resets `CO`.
126 #[display("ldo immutable")]
127 LdOAo,
128
129 /// Load destructible input witness [`StateValue`] for the current input number (determined by
130 /// the value in `UI` register) to `EA`-`ED` registers.
131 ///
132 /// The operation is idempotent.
133 ///
134 /// Does not update the value of `UI` register.
135 ///
136 /// If the input matching `UI` index is absent, sets `CO` to a failed state.
137 /// Otherwise, resets `CO`.
138 #[display("ldi witness")]
139 LdIW,
140
141 /// Load a lock conditions value for the current input number (determined by the value in `UI`
142 /// register) to `EA`-`ED` registers.
143 ///
144 /// The operation is idempotent.
145 ///
146 /// Does not update the value of `UI` register.
147 ///
148 /// If the input matching `UI` index is absent, sets `CO` to a failed state.
149 /// Otherwise, resets `CO`.
150 #[display("ldi lock")]
151 LdIL,
152
153 /// Load a destructible input authorization token [`AuthToken`] for the current input number
154 /// (determined by the value in `UI` register) to `EA` register.
155 ///
156 /// The operation also sets `EB` to either `0` (if a custom lock script is not present)
157 /// or `1`, if it is present.
158 ///
159 /// The operation is idempotent.
160 ///
161 /// Does not update the value of `UI` register.
162 ///
163 /// If the input matching `UI` index is absent, sets `CO` to a failed state.
164 /// Otherwise, resets `CO`.
165 #[display("ldi auth")]
166 LdIT,
167
168 /// Resets iterator over the input destructible memory cells by setting the corresponding `UI`
169 /// value to zero.
170 ///
171 /// Does not affect the value of `CO` or `CK` registers.
172 #[display("rsti destructible")]
173 RstIRo,
174
175 /// Resets iterator over the input immutable memory cells by setting the corresponding `UI`
176 /// value to zero.
177 ///
178 /// Does not affect the value of `CO` or `CK` registers.
179 #[display("rsti immutable")]
180 RstIAo,
181
182 /// Resets iterator over the output destructible memory cells by setting the corresponding `UI`
183 /// value to zero.
184 ///
185 /// Does not affect the value of `CO` or `CK` registers.
186 #[display("rsto destructible")]
187 RstORo,
188
189 /// Resets iterator over the output immutable memory cells by setting the corresponding `UI`
190 /// value to zero.
191 ///
192 /// Does not affect the value of `CO` or `CK` registers.
193 #[display("rsto immutable")]
194 RstOAo,
195}