carbon_core/
collection.rs

1//! Provides traits and utilities for decoding and managing collections of
2//! Solana instructions.
3//!
4//! This module defines the `InstructionDecoderCollection` trait, which enables
5//! decoding of Solana `Instruction` objects into structured types, allowing for
6//! streamlined processing of instructions in a `carbon-core` pipeline. The
7//! trait abstracts the decoding logic, providing an easy way to parse various
8//! instruction types and retrieve their corresponding metadata for further
9//! processing.
10//!
11//! # Overview
12//!
13//! The `InstructionDecoderCollection` trait is designed to support the handling
14//! of different Solana instructions within a unified pipeline. Implementations
15//! of this trait are expected to define how each instruction is decoded and
16//! represented as an internal type, facilitating efficient management and
17//! manipulation of instruction data.
18//!
19//! Key features include:
20//! - **Instruction Type Association**: Associates instructions with specific
21//!   types, allowing for the decoding of multiple instruction types within a
22//!   single collection.
23//! - **Parsing Capability**: Provides a standardized method to parse Solana
24//!   instructions into custom types suitable for application logic.
25//! - **Type Retrieval**: Includes a method for retrieving the instruction type
26//!   associated with each instance, enabling easy type-based routing or
27//!   processing.
28//!
29//! # Notes
30//!
31//! - Implementations must be `Clone`, `Debug`, `Send`, `Sync`, `Eq`, `Hash`,
32//!   and `Serialize`, making them suitable for concurrent and distributed
33//!   environments where instruction collections need to be transmitted, cloned,
34//!   or processed in parallel.
35//! - This module assumes familiarity with Solana's `Instruction` type and its
36//!   role in transaction processing.
37//!
38//! Use the `InstructionDecoderCollection` trait to build flexible, type-safe
39//! instruction handling within your application, benefiting from simplified
40//! parsing and type management capabilities.
41
42use {crate::instruction::DecodedInstruction, serde::Serialize};
43
44/// A trait for defining collections of Solana instructions, enabling parsing
45/// and type-based management.
46///
47/// The `InstructionDecoderCollection` trait provides an interface for decoding
48/// Solana `Instruction` objects into custom types that can be processed within
49/// the `carbon-core` pipeline. This trait requires implementing methods to
50/// parse instructions and retrieve associated instruction types, allowing for
51/// flexible handling of different instruction variants in a single collection.
52///
53/// ## Associated Types
54///
55/// - `InstructionType`: Defines the specific type of instruction being handled,
56///   which is expected to be `Clone`, `Debug`, `PartialEq`, `Eq`, `Send`, and
57///   `Sync`. This type is used to classify decoded instructions, making them
58///   easier to process based on their category or type.
59///
60/// ## Required Methods
61///
62/// ### `parse_instruction`
63///
64/// This method is responsible for converting a Solana `Instruction` object into
65/// a `DecodedInstruction` containing the custom type defined by the
66/// implementor. The parsed instruction can then be processed within the
67/// pipeline according to application-specific logic.
68///
69/// - **Parameters**:
70///   - `instruction`: A reference to a `solana_instruction::Instruction`,
71///     representing the raw instruction to be decoded.
72/// - **Returns**: An `Option<DecodedInstruction<Self>>` containing the decoded
73///   instruction if successful, or `None` if parsing fails or the instruction
74///   is unsupported.
75///
76/// ### `get_type`
77///
78/// Retrieves the instruction type associated with an instruction. This type can
79/// be used to classify instructions or route them to specific processing logic
80/// based on their category.
81///
82/// - **Returns**: An instance of `Self::InstructionType`, representing the
83///   specific type of instruction.
84///
85/// ## Notes
86///
87/// - This trait requires implementors to be thread-safe (`Send` and `Sync`) and
88///   serializable (`Serialize`), which is particularly useful for distributed
89///   systems where instruction collections are transmitted across network
90///   boundaries.
91/// - The `parse_instruction` method must be implemented with care, as it
92///   determines how raw instruction data is transformed into a decoded form,
93///   impacting subsequent processing within the pipeline.
94pub trait InstructionDecoderCollection:
95    Clone + std::fmt::Debug + Send + Sync + Eq + std::hash::Hash + Serialize + 'static
96{
97    type InstructionType: Clone + std::fmt::Debug + PartialEq + Eq + Send + Sync + 'static;
98
99    fn parse_instruction(
100        instruction: &solana_instruction::Instruction,
101    ) -> Option<DecodedInstruction<Self>>;
102    fn get_type(&self) -> Self::InstructionType;
103}
carbon_core/collection.rs

carbon_core/
collection.rs
