simplicity/node/
hiding.rs

1use crate::node::{
2    CoreConstructible, DisconnectConstructible, JetConstructible, WitnessConstructible,
3};
4use crate::types::{Context, Error};
5use crate::{Cmr, FailEntropy, HasCmr, Word};
6
7/// Wrapper that allows a node to be "hidden" during program construction.
8///
9/// ## Program construction
10///
11/// When a program is constructed in post-order,
12/// the parent node is created based on its children.
13/// We use this fact to introduce special branching logic:
14///
15/// 1. A `case` node with a left "hidden" child and a right non-hidden child becomes `assertr`.
16/// 2. A `case` node with a left non-hidden child and a right "hidden" child becomes `assertl`.
17/// 3. Otherwise, any node with "hidden" children becomes itself "hidden" with an updated CMR.
18/// 4. Any node with non-hidden children remains unchanged.
19///
20/// The program can be extracted from the wrapper when construction is finished.
21/// The program is invalid if the root node is "hidden".
22///
23/// ## Wrapping
24///
25/// A node can be wrapped via [`Hiding::from`] to add hiding support.
26/// A wrapped node can be converted into a "hidden" node via [`Hiding::hide`].
27/// Finally, a "hidden" node can be manually created via [`Hiding::hidden`].
28///
29/// ## Virtual hidden nodes
30///
31/// The wrapper merely _simulates_ hidden nodes.
32/// At no point are actual hidden nodes created.
33/// To stress this fact, I write "hidden" in quotation marks.
34#[derive(Clone, Debug, Eq, PartialEq)]
35pub struct Hiding<N> {
36    result: HidingResult<N>,
37    /// Inference context for program construction.
38    ///
39    /// Even a "hidden" node needs an inference context
40    /// because the context may be queried via [`CoreConstructible::inference_context`].
41    /// When a "hidden" node is converted into an assertion via the
42    /// [`CoreConstructible::case`] constructor, this context is required to build the case node.
43    /// For soundness, the same context should be returned for all nodes of the same program.
44    ctx: Context,
45}
46
47type HidingResult<N> = Result<N, Cmr>;
48
49impl<N> Hiding<N> {
50    /// Create a "hidden" node with the given CMR.
51    ///
52    /// To enable the construction of possible parent nodes,
53    /// the inference context of the current program must be passed.
54    pub const fn hidden(cmr: Cmr, ctx: Context) -> Self {
55        // # Soundness
56        // The hidden node introduces no type variables.
57        Self {
58            result: Err(cmr),
59            ctx,
60        }
61    }
62
63    fn hidden_cloned_ctx(&self, cmr: Cmr) -> Self {
64        Self {
65            result: Err(cmr),
66            ctx: self.ctx.shallow_clone(),
67        }
68    }
69
70    /// Access the non-hidden node inside in the wrapper.
71    ///
72    /// Return `None` if the wrapped node is "hidden".
73    pub fn as_node(&self) -> Option<&N> {
74        self.result.as_ref().ok()
75    }
76
77    /// Consume the wrapper and return the non-hidden node that was inside.
78    ///
79    /// Return `None` if the wrapped node is "hidden".
80    pub fn get_node(self) -> Option<N> {
81        self.result.ok()
82    }
83}
84
85impl<N: HasCmr> Hiding<N> {
86    /// Ensure that the wrapped node is "hidden".
87    /// Convert non-hidden nodes into "hidden" nodes with the same CMR.
88    pub fn hide(self) -> Self {
89        // # Soundness
90        // Hiding a node means converting it into its CMR.
91        // The node's type variables remain in the inference context.
92        //
93        // The type variables of a "hidden" child don't influence the construction of a parent,
94        // because merely the child's CMR is passed to the parent constructor.
95        // A CMR has no connection to any type variables.
96        //
97        // Hiding a node creates a CMR that is independent from the original node.
98        // The CMR can be used in one part of the program
99        // while the node itself is used in a different part.
100        match self.result {
101            Ok(node) => Self::hidden(node.cmr(), self.ctx),
102            Err(..) => self,
103        }
104    }
105}
106
107impl<N: HasCmr> HasCmr for Hiding<N> {
108    fn cmr(&self) -> Cmr {
109        match &self.result {
110            Ok(node) => node.cmr(),
111            Err(cmr) => *cmr,
112        }
113    }
114}
115
116// We need `N: CoreConstructible` to access the inference context.
117// Because of this, implementations of `{Jet, Disconnect, Witness}Constructible`
118// for `Hiding<N>` require `N: CoreConstructible`.
119impl<N: CoreConstructible> From<N> for Hiding<N> {
120    fn from(node: N) -> Self {
121        Self {
122            ctx: node.inference_context().shallow_clone(),
123            result: Ok(node),
124        }
125    }
126}
127
128// # Soundness
129// See [`Hiding::hide`].
130impl<N: CoreConstructible + HasCmr> CoreConstructible for Hiding<N> {
131    fn iden(inference_context: &Context) -> Self {
132        N::iden(inference_context).into()
133    }
134
135    fn unit(inference_context: &Context) -> Self {
136        N::unit(inference_context).into()
137    }
138
139    fn injl(child: &Self) -> Self {
140        match &child.result {
141            Ok(child) => N::injl(child).into(),
142            Err(cmr) => child.hidden_cloned_ctx(Cmr::injl(*cmr)),
143        }
144    }
145
146    fn injr(child: &Self) -> Self {
147        match &child.result {
148            Ok(child) => N::injr(child).into(),
149            Err(cmr) => child.hidden_cloned_ctx(Cmr::injr(*cmr)),
150        }
151    }
152
153    fn take(child: &Self) -> Self {
154        match &child.result {
155            Ok(child) => N::take(child).into(),
156            Err(cmr) => child.hidden_cloned_ctx(Cmr::take(*cmr)),
157        }
158    }
159
160    fn drop_(child: &Self) -> Self {
161        match &child.result {
162            Ok(child) => N::drop_(child).into(),
163            Err(cmr) => child.hidden_cloned_ctx(Cmr::drop(*cmr)),
164        }
165    }
166
167    fn comp(left: &Self, right: &Self) -> Result<Self, Error> {
168        match (&left.result, &right.result) {
169            (Ok(left), Ok(right)) => N::comp(left, right).map(Self::from),
170            _ => Ok(left.hidden_cloned_ctx(Cmr::comp(left.cmr(), right.cmr()))),
171        }
172    }
173
174    fn case(left: &Self, right: &Self) -> Result<Self, Error> {
175        match (&left.result, &right.result) {
176            (Ok(left), Ok(right)) => N::case(left, right).map(Self::from),
177            (Err(left), Ok(right)) => N::assertr(*left, right).map(Self::from),
178            (Ok(left), Err(right)) => N::assertl(left, *right).map(Self::from),
179            _ => Ok(left.hidden_cloned_ctx(Cmr::case(left.cmr(), right.cmr()))),
180        }
181    }
182
183    fn assertl(left: &Self, right: Cmr) -> Result<Self, Error> {
184        match &left.result {
185            Ok(left) => N::assertl(left, right).map(Self::from),
186            _ => Ok(left.hidden_cloned_ctx(Cmr::case(left.cmr(), right))),
187        }
188    }
189
190    fn assertr(left: Cmr, right: &Self) -> Result<Self, Error> {
191        match &right.result {
192            Ok(right) => N::assertr(left, right).map(Self::from),
193            _ => Ok(right.hidden_cloned_ctx(Cmr::case(left, right.cmr()))),
194        }
195    }
196
197    fn pair(left: &Self, right: &Self) -> Result<Self, Error> {
198        match (&left.result, &right.result) {
199            (Ok(left), Ok(right)) => N::pair(left, right).map(Self::from),
200            _ => Ok(left.hidden_cloned_ctx(Cmr::pair(left.cmr(), right.cmr()))),
201        }
202    }
203
204    fn fail(inference_context: &Context, entropy: FailEntropy) -> Self {
205        N::fail(inference_context, entropy).into()
206    }
207
208    fn const_word(inference_context: &Context, word: Word) -> Self {
209        N::const_word(inference_context, word).into()
210    }
211
212    fn inference_context(&self) -> &Context {
213        &self.ctx
214    }
215}
216
217impl<J, N> JetConstructible<J> for Hiding<N>
218where
219    N: JetConstructible<J> + CoreConstructible,
220{
221    fn jet(inference_context: &Context, jet: J) -> Self {
222        N::jet(inference_context, jet).into()
223    }
224}
225
226impl<X, N> DisconnectConstructible<Option<X>> for Hiding<N>
227where
228    N: DisconnectConstructible<Option<X>> + CoreConstructible + HasCmr,
229{
230    fn disconnect(left: &Self, right: &Option<X>) -> Result<Self, Error> {
231        match &left.result {
232            Ok(left) => N::disconnect(left, right).map(Self::from),
233            Err(..) => Ok(left.hidden_cloned_ctx(Cmr::disconnect(left.cmr()))),
234        }
235    }
236}
237
238impl<W, N> WitnessConstructible<W> for Hiding<N>
239where
240    N: WitnessConstructible<W> + CoreConstructible,
241{
242    fn witness(inference_context: &Context, witness: W) -> Self {
243        N::witness(inference_context, witness).into()
244    }
245}
simplicity/node/hiding.rs

simplicity/node/
hiding.rs
