0.5.1-pre.002

ks-lib/src/executor/api/executor.rs

@@ -0,0 +1,109 @@
+// file: ks-lib/src/executor/api/executor.rs
+// version: 5
+
+//! Shared execution contract and neutral request models.
+
+use ts_rs::TS; // rust-rules: derive-import
+
+/// Support level returned by an executor for a requested operation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, TS)]
+#[ts(
+    export,
+    export_to = "../frontend/ts/bindings/ks_lib/executor/api/executor/ExecutionSupport.ts"
+)]
+pub enum ExApiExecutionSupport {
+    /// The executor cannot handle the request.
+    No,
+    /// The executor may handle the request after account and payload validation.
+    Maybe,
+    /// The executor explicitly supports the request.
+    Yes,
+}
+
+/// Generic request used before protocol-specific execution models are introduced.
+#[derive(Clone, Debug, Eq, PartialEq, TS)]
+#[ts(
+    export,
+    export_to = "../frontend/ts/bindings/ks_lib/executor/api/executor/ExecutionRequest.ts"
+)]
+pub struct ExApiExecutionRequest {
+    /// Target program id.
+    pub program_id: crate::MdProgramId,
+    /// Stable operation code such as buy, sell, transfer or route.
+    pub operation_code: std::string::String,
+    /// Serialized JSON payload reserved for protocol-specific arguments.
+    pub payload_json: std::string::String,
+}
+
+/// Neutral execution plan placeholder produced by executor crates.
+#[derive(Clone, Debug, Eq, PartialEq, TS)]
+#[ts(
+    export,
+    export_to = "../frontend/ts/bindings/ks_lib/executor/api/executor/ExecutionPlan.ts"
+)]
+pub struct ExApiExecutionPlan {
+    /// Stable executor crate name.
+    pub executor_name: std::string::String,
+    /// Number of instructions that would be produced by the final implementation.
+    pub instruction_count: usize,
+    /// Serialized JSON payload reserved for future instruction data and account metadata.
+    pub payload_json: std::string::String,
+}
+
+/// Serializes a JSON payload to its compact string representation.
+pub fn executor_api_serialize_payload_json(
+    value: &serde_json::Value,
+) -> ks_core::Result<std::string::String> {
+    return match serde_json::to_string(value) {
+        std::result::Result::Ok(serialized) => std::result::Result::Ok(serialized),
+        std::result::Result::Err(error) => std::result::Result::Err(ks_core::Error::new(
+            "execution_payload_json_serialize_failed",
+            error.to_string(),
+        )),
+    };
+}
+
+/// Serializes a JSON payload to its pretty string representation.
+pub fn executor_api_serialize_payload_json_pretty(
+    value: &serde_json::Value,
+) -> ks_core::Result<std::string::String> {
+    return match serde_json::to_string_pretty(value) {
+        std::result::Result::Ok(serialized) => std::result::Result::Ok(serialized),
+        std::result::Result::Err(error) => std::result::Result::Err(ks_core::Error::new(
+            "execution_payload_json_pretty_serialize_failed",
+            error.to_string(),
+        )),
+    };
+}
+
+/// Common contract implemented by all execution crates.
+pub trait ExApiInstructionExecutor {
+    /// Returns the stable executor name.
+    fn executor_name(&self) -> &'static str;
+
+    /// Returns the executor version.
+    fn executor_version(&self) -> &'static str;
+
+    /// Returns the program ids handled by this executor.
+    fn program_ids(&self) -> &'static [&'static str];
+
+    /// Tests whether this executor owns a program id.
+    fn handles_program_id(&self, program_id: &crate::MdProgramId) -> bool {
+        return self
+            .program_ids()
+            .iter()
+            .any(|candidate| return *candidate == program_id.0.as_str());
+    }
+
+    /// Tests whether this executor supports a request.
+    fn supports_request(
+        &self,
+        request: &crate::ExApiExecutionRequest,
+    ) -> crate::ExApiExecutionSupport;
+
+    /// Builds a neutral execution plan placeholder.
+    fn build_plan(
+        &self,
+        request: &crate::ExApiExecutionRequest,
+    ) -> ks_core::Result<crate::ExApiExecutionPlan>;
+}