Skip to main content

sui_rpc_api/grpc/v2/
render.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use std::sync::{Arc, OnceLock};
5
6use futures::FutureExt;
7use move_core_types::annotated_value::MoveTypeLayout;
8use move_core_types::language_storage::{StructTag, TypeTag};
9use mysten_common::ZipDebugEqIteratorExt;
10use prost_types::Struct;
11use sui_package_resolver::{Limits as ResolverLimits, PackageStoreWithLruCache, SyncResolver};
12use sui_protocol_config::{ProtocolConfig, max_across_protocol};
13use sui_rpc::{
14    field::FieldMaskTree,
15    merge::Merge,
16    proto::sui::rpc::v2::{
17        Bcs, Display, Event, ExecutedTransaction, Object, TransactionEffects, TransactionEvents,
18    },
19};
20use sui_types::full_checkpoint_content::ObjectSet;
21use sui_types::storage::{BackingPackageStore, OverlayBackingPackageStore, RpcStateReader};
22
23use crate::{RpcService, reader::DisplayStore};
24
25type CachedLayoutResolver<'a> =
26    SyncResolver<PackageStoreWithLruCache<Box<dyn BackingPackageStore + Send + Sync + 'a>>>;
27
28fn resolver_limits() -> ResolverLimits {
29    static LIMITS: OnceLock<ResolverLimits> = OnceLock::new();
30
31    LIMITS
32        .get_or_init(|| ResolverLimits {
33            max_type_argument_depth: max_across_protocol(
34                ProtocolConfig::max_type_argument_depth_as_option,
35            )
36            .unwrap_or(u32::MAX) as usize,
37            max_type_argument_width: max_across_protocol(
38                ProtocolConfig::max_generic_instantiation_length_as_option,
39            )
40            .unwrap_or(u32::MAX as u64) as usize,
41            max_type_nodes: max_across_protocol(ProtocolConfig::max_type_nodes_as_option)
42                .unwrap_or(u32::MAX as u64) as usize,
43            max_move_value_depth: max_across_protocol(
44                ProtocolConfig::max_move_value_depth_as_option,
45            )
46            .unwrap_or(u32::MAX as u64) as usize,
47            max_layout_work: sui_package_resolver::DEFAULT_MAX_LAYOUT_WORK,
48        })
49        .clone()
50}
51
52/// Reuses parsed packages while rendering a response against a fixed object overlay.
53pub(crate) struct RenderContext<'a> {
54    reader: &'a dyn RpcStateReader,
55    overlay: Option<&'a ObjectSet>,
56    layout_resolver: OnceLock<CachedLayoutResolver<'a>>,
57}
58
59impl<'a> RenderContext<'a> {
60    pub(crate) fn empty(reader: &'a Arc<dyn RpcStateReader>) -> Self {
61        Self::new(reader, None)
62    }
63
64    pub(crate) fn new(reader: &'a Arc<dyn RpcStateReader>, overlay: Option<&'a ObjectSet>) -> Self {
65        Self {
66            reader: reader.as_ref(),
67            // An empty overlay can use the backing store directly.
68            overlay: overlay.filter(|objects| !objects.is_empty()),
69            layout_resolver: OnceLock::new(),
70        }
71    }
72
73    pub(crate) fn type_layout(
74        &self,
75        type_tag: TypeTag,
76    ) -> sui_package_resolver::Result<MoveTypeLayout> {
77        self.layout_resolver().type_layout(type_tag)
78    }
79
80    fn layout_resolver(&self) -> &CachedLayoutResolver<'a> {
81        self.layout_resolver.get_or_init(|| {
82            let mut store = self.reader.layout_package_store();
83            if let Some(overlay) = self.overlay {
84                store = Box::new(OverlayBackingPackageStore::new(overlay, store));
85            }
86            SyncResolver::new_with_limits(PackageStoreWithLruCache::new(store), resolver_limits())
87        })
88    }
89}
90
91impl RpcService {
92    pub(crate) fn render_object_to_proto(
93        &self,
94        object: &sui_types::object::Object,
95        read_mask: &FieldMaskTree,
96        context: &RenderContext,
97    ) -> Object {
98        let mut message = Object::default();
99
100        if read_mask.contains(Object::JSON_FIELD) {
101            let move_object = object.data.try_as_move();
102            message.json = move_object.and_then(|m| {
103                self.render_json(&m.type_().clone().into(), m.contents(), context)
104                    .map(Box::new)
105            });
106        }
107
108        if read_mask.contains(Object::DISPLAY_FIELD) {
109            message.display = self.render_object_display(object, context).map(Box::new);
110        }
111
112        message.merge(object, read_mask);
113
114        message
115    }
116
117    /// Render a Move value as JSON using the response's package cache and overlay.
118    fn render_json(
119        &self,
120        struct_tag: &StructTag,
121        contents: &[u8],
122        context: &RenderContext,
123    ) -> Option<prost_types::Value> {
124        let mut budget = self.config.max_json_move_value_size();
125        self.render_json_with_budget(struct_tag, contents, context, &mut budget)
126    }
127
128    /// Render a Move value as JSON, drawing the size budget from a caller-owned
129    /// counter. Endpoints that render many Move values in a single response
130    /// (e.g. every event in a checkpoint) share one budget across all renders
131    /// to bound the aggregate response memory rather than multiplying the
132    /// per-render limit by the number of items. The budget is updated in place
133    /// to reflect bytes consumed; once it reaches zero subsequent calls fail
134    /// fast and return `None`.
135    fn render_json_with_budget(
136        &self,
137        struct_tag: &StructTag,
138        contents: &[u8],
139        context: &RenderContext,
140        size_budget: &mut usize,
141    ) -> Option<prost_types::Value> {
142        let layout = context
143            .type_layout(TypeTag::Struct(Box::new(struct_tag.clone())))
144            .ok()?;
145
146        sui_types::object::rpc_visitor::proto::ProtoVisitor::deserialize_value_with_budget(
147            contents,
148            &layout,
149            size_budget,
150        )
151        .map_err(|e| tracing::debug!("unable to convert move value to JSON: {e}"))
152        .ok()
153    }
154
155    fn render_object_display(
156        &self,
157        object: &sui_types::object::Object,
158        context: &RenderContext,
159    ) -> Option<Display> {
160        let move_object = object.data.try_as_move()?;
161        let object_type = &move_object.type_().clone().into();
162        let contents = move_object.contents();
163
164        let limits = sui_display::v2::Limits {
165            max_depth: self.config.display().max_field_depth(),
166            max_nodes: self.config.display().max_format_nodes(),
167            max_loads: self.config.display().max_object_loads(),
168        };
169        let display_object = self.reader.get_display_object_v2_by_type(object_type)?;
170        let display_template =
171            sui_display::v2::Display::parse(limits, display_object.fields()).ok()?;
172
173        let resolver = context.layout_resolver();
174        let layout = resolver.datatype_layout(object_type).ok()?.into_layout();
175
176        let root = sui_display::v2::OwnedSlice::new(layout, contents.to_owned());
177        let interpreter =
178            sui_display::v2::Interpreter::new(root, DisplayStore::new(&self.reader, resolver));
179
180        let mut display = Display::default();
181
182        // The display api requires that the `sui_display::v2::Store` is async. We know that the
183        // Store implementation we are passing in here is fully synchronous, doing db access
184        // in-place and as such should never return Poll::Pending.
185        match display_template
186            .display::<prost_types::Value>(
187                self.config.display().max_move_value_depth(),
188                self.config.display().max_output_size(),
189                &interpreter,
190            )
191            .now_or_never()
192            .unwrap()
193        {
194            Ok(rendered) => {
195                let mut output = Struct::default();
196                let mut errors = Struct::default();
197
198                for (field, result) in rendered {
199                    match result {
200                        Ok(value) => {
201                            output.fields.insert(field, value);
202                        }
203                        Err(e) => {
204                            errors.fields.insert(field, e.to_string().into());
205                        }
206                    }
207                }
208
209                if !output.fields.is_empty() {
210                    display.set_output(output.fields);
211                }
212
213                if !errors.fields.is_empty() {
214                    display.set_errors(errors.fields);
215                }
216            }
217            Err(e) => {
218                display.set_errors(e.to_string());
219            }
220        }
221
222        Some(display)
223    }
224
225    pub(crate) fn render_events_to_proto(
226        &self,
227        events: &sui_types::effects::TransactionEvents,
228        mask: &FieldMaskTree,
229        context: &RenderContext,
230    ) -> TransactionEvents {
231        let mut message = TransactionEvents::default();
232
233        if mask.contains(TransactionEvents::BCS_FIELD) {
234            let mut bcs = Bcs::serialize(&events).unwrap();
235            bcs.name = Some("TransactionEvents".to_owned());
236            message.bcs = Some(bcs);
237        }
238
239        if mask.contains(TransactionEvents::DIGEST_FIELD) {
240            message.digest = Some(events.digest().to_string());
241        }
242
243        if let Some(event_mask) = mask.subtree(TransactionEvents::EVENTS_FIELD) {
244            message.events = events
245                .data
246                .iter()
247                .map(|event| self.render_event_to_proto(event, &event_mask, context))
248                .collect();
249        }
250
251        message
252    }
253
254    pub(crate) fn render_event_to_proto(
255        &self,
256        event: &sui_types::event::Event,
257        mask: &FieldMaskTree,
258        context: &RenderContext,
259    ) -> Event {
260        let mut message = Event::default();
261
262        if mask.contains(Event::PACKAGE_ID_FIELD) {
263            message.set_package_id(event.package_id.to_canonical_string(true));
264        }
265
266        if mask.contains(Event::MODULE_FIELD) {
267            message.set_module(event.transaction_module.to_string());
268        }
269
270        if mask.contains(Event::SENDER_FIELD) {
271            message.sender = Some(event.sender.to_string());
272        }
273
274        if mask.contains(Event::EVENT_TYPE_FIELD) {
275            message.event_type = Some(event.type_.to_canonical_string(true));
276        }
277
278        if mask.contains(Event::CONTENTS_FIELD) {
279            let mut bcs = Bcs::from(event.contents.clone());
280            bcs.name = Some(event.type_.to_canonical_string(true));
281            message.contents = Some(bcs);
282        }
283
284        if mask.contains(Event::JSON_FIELD) {
285            message.json = self
286                .render_json(&event.type_, &event.contents, context)
287                .map(Box::new);
288        }
289
290        message
291    }
292
293    // Renders clever error information in-place
294    pub fn render_clever_error(&self, effects: &mut TransactionEffects) {
295        use sui_rpc::proto::sui::rpc::v2::CleverError;
296        use sui_rpc::proto::sui::rpc::v2::MoveAbort;
297        use sui_rpc::proto::sui::rpc::v2::clever_error;
298        use sui_rpc::proto::sui::rpc::v2::execution_error::ErrorDetails;
299
300        let Some(move_abort) = effects
301            .status
302            .as_mut()
303            .and_then(|status| status.error.as_mut())
304            .and_then(|error| match &mut error.error_details {
305                Some(ErrorDetails::Abort(move_abort)) => Some(move_abort),
306                _ => None,
307            })
308        else {
309            return;
310        };
311
312        fn render(service: &RpcService, move_abort: &MoveAbort) -> Option<CleverError> {
313            let location = move_abort.location.as_ref()?;
314            let abort_code = move_abort.abort_code();
315            let package_id = location.package().parse::<sui_sdk_types::Address>().ok()?;
316            let module = location.module();
317
318            let package = {
319                let object = service.reader.inner().get_object(&package_id.into())?;
320                sui_package_resolver::Package::read_from_object(&object).ok()?
321            };
322
323            let clever_error = package.resolve_clever_error(module, abort_code)?;
324
325            let mut clever_error_message = CleverError::default();
326
327            match clever_error.error_info {
328                sui_package_resolver::ErrorConstants::None => {}
329                sui_package_resolver::ErrorConstants::Rendered {
330                    identifier,
331                    constant,
332                } => {
333                    clever_error_message.constant_name = Some(identifier);
334                    clever_error_message.value = Some(clever_error::Value::Rendered(constant));
335                }
336                sui_package_resolver::ErrorConstants::Raw { identifier, bytes } => {
337                    clever_error_message.constant_name = Some(identifier);
338                    clever_error_message.value = Some(clever_error::Value::Raw(bytes.into()));
339                }
340            }
341
342            clever_error_message.error_code = clever_error.error_code.map(Into::into);
343            clever_error_message.line_number = Some(clever_error.source_line_number.into());
344
345            Some(clever_error_message)
346        }
347
348        move_abort.clever_error = render(self, move_abort);
349    }
350
351    pub fn render_effects_to_proto(
352        &self,
353        effects: &sui_types::effects::TransactionEffects,
354        unchanged_loaded_runtime_objects: &[sui_types::storage::ObjectKey],
355        objects: &ObjectSet,
356        mask: &FieldMaskTree,
357    ) -> TransactionEffects {
358        // TODO consider inlining this function here to avoid needing to do the extra parsing below
359        let mut message = TransactionEffects::merge_from(effects, mask);
360
361        if mask.contains(TransactionEffects::UNCHANGED_LOADED_RUNTIME_OBJECTS_FIELD) {
362            message.unchanged_loaded_runtime_objects = unchanged_loaded_runtime_objects
363                .iter()
364                .map(Into::into)
365                .collect();
366        }
367
368        self.annotate_effects(&mut message, objects, mask);
369
370        message
371    }
372
373    /// Fill the effects fields that `TransactionEffects::merge_from` cannot: the
374    /// object types of changed and unchanged consensus objects, looked up in
375    /// `objects`, and the clever error of a Move abort.
376    pub fn annotate_effects(
377        &self,
378        effects: &mut TransactionEffects,
379        objects: &ObjectSet,
380        mask: &FieldMaskTree,
381    ) {
382        if mask.contains(TransactionEffects::CHANGED_OBJECTS_FIELD) {
383            for changed_object in effects.changed_objects.iter_mut() {
384                let Ok(object_id) = changed_object
385                    .object_id()
386                    .parse::<sui_types::base_types::ObjectID>()
387                else {
388                    continue;
389                };
390
391                if let Some(object) = objects.get(&sui_types::storage::ObjectKey(
392                    object_id,
393                    changed_object
394                        .input_version_opt()
395                        .unwrap_or_else(|| changed_object.output_version())
396                        .into(),
397                )) {
398                    changed_object.set_object_type(object_type_to_string(object.into()));
399                }
400            }
401        }
402
403        if mask.contains(TransactionEffects::UNCHANGED_CONSENSUS_OBJECTS_FIELD) {
404            for unchanged_consensus_object in effects.unchanged_consensus_objects.iter_mut() {
405                let Ok(object_id) = unchanged_consensus_object
406                    .object_id()
407                    .parse::<sui_types::base_types::ObjectID>()
408                else {
409                    continue;
410                };
411
412                if let Some(object) = objects.get(&sui_types::storage::ObjectKey(
413                    object_id,
414                    unchanged_consensus_object.version().into(),
415                )) {
416                    unchanged_consensus_object
417                        .set_object_type(object_type_to_string(object.into()));
418                }
419            }
420        }
421
422        // Try to render clever error info
423        self.render_clever_error(effects);
424    }
425
426    /// Fill the parts of an `ExecutedTransaction` merged from checkpoint data
427    /// that `merge_from` cannot: effects object types and clever errors (see
428    /// [`Self::annotate_effects`]) and event JSON, which needs the package
429    /// resolver. Event JSON draws from `json_budget`, which the caller shares
430    /// across every event in one response.
431    pub(crate) fn annotate_checkpoint_transaction(
432        &self,
433        message: &mut ExecutedTransaction,
434        transaction: &sui_types::full_checkpoint_content::ExecutedTransaction,
435        objects: &ObjectSet,
436        mask: &FieldMaskTree,
437        json_budget: &mut usize,
438        context: &RenderContext,
439    ) {
440        if let Some(effects_mask) = mask.subtree(ExecutedTransaction::EFFECTS_FIELD)
441            && let Some(effects) = message.effects.as_mut()
442        {
443            self.annotate_effects(effects, objects, &effects_mask);
444        }
445
446        if let Some(events_mask) = mask.subtree(ExecutedTransaction::EVENTS_FIELD)
447            && let Some(event_mask) = events_mask.subtree(TransactionEvents::EVENTS_FIELD)
448            && event_mask.contains(Event::JSON_FIELD)
449            && let Some(rendered) = message.events.as_mut()
450            && let Some(events) = &transaction.events
451        {
452            for (event_message, event) in rendered.events.iter_mut().zip_debug_eq(&events.data) {
453                event_message.json = self
454                    .render_json_with_budget(&event.type_, &event.contents, context, json_budget)
455                    .map(Box::new);
456            }
457        }
458    }
459}
460
461fn object_type_to_string(object_type: sui_types::base_types::ObjectType) -> String {
462    match object_type {
463        sui_types::base_types::ObjectType::Package => "package".to_owned(),
464        sui_types::base_types::ObjectType::Struct(move_object_type) => {
465            move_object_type.to_canonical_string(true)
466        }
467    }
468}