feat(xdr): define a versioned JSON schema for decoded values

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `devkit-xdr`: versioned decoded-XDR JSON schema (`schema_version` `1.0`) for
+  `ScVal`, `TransactionEnvelope`, and `ContractEvent`, an opt-in `raw_xdr`
+  echo (`--raw`), golden snapshots, and the `docs/XDR.md` and `docs/SCVAL.md`
+  schema references.
+
 ## [0.1.0] - 2026-10-28
 
 First tagged release. Prebuilt binaries for Linux x86_64, macOS arm64, and

README.md

@@ -20,8 +20,9 @@ The core works fully **offline** and never requires AI.
 
 - `devkit-core` — shared errors, network profiles, output format.
 - `devkit-xdr` — decode `ScVal`, `TransactionEnvelope`, and `ContractEvent` from
-  base64 XDR into JSON; classify Stellar strkeys; bounded malformed-input
-  handling.
+  base64 XDR into a versioned JSON document (`schema_version` 1.0) with an
+  opt-in `raw_xdr` echo; classify Stellar strkeys; bounded malformed-input
+  handling. See [docs/XDR.md](docs/XDR.md) and [docs/SCVAL.md](docs/SCVAL.md).
 - `devkit-rpc` — endpoint validation, typed protocol layer, deterministic mock
   transport, retry policy, and a bounded HTTP JSON-RPC transport.
 - `devkit-contract` — non-executing WASM validation, import/export/custom-section
@@ -106,6 +107,8 @@ Decode commands accept `-` to read one bounded value from stdin. Exit codes:
 - [Architecture](docs/ARCHITECTURE.md)
 - [Getting started](docs/GETTING_STARTED.md)
 - [CLI reference](docs/CLI.md)
+- [XDR JSON schema](docs/XDR.md)
+- [SCVal JSON schema](docs/SCVAL.md)
 - [Configuration](docs/CONFIGURATION.md)
 - [Implemented capabilities](docs/IMPLEMENTED_CAPABILITIES.md)
 - [Memory measurement](docs/MEMORY.md)

crates/devkit-cli/src/main.rs

@@ -49,6 +49,10 @@ struct Cli {
     #[arg(long, value_enum, default_value_t = FormatArg::Terminal, global = true)]
     format: FormatArg,
 
+    /// Include the raw base64 XDR input in decoded JSON output.
+    #[arg(long, global = true)]
+    raw: bool,
+
     #[command(subcommand)]
     command: Command,
 }
@@ -173,6 +177,9 @@ fn print_json_error(category: &str, message: &str) {
 
 fn run(cli: Cli) -> Result<u8, CliError> {
     let format: OutputFormat = cli.format.into();
+    let options = xdr::DecodeOptions {
+        include_raw: cli.raw,
+    };
     let config_path = cli.config.clone();
     match cli.command {
         Command::Version => {
@@ -192,20 +199,23 @@ fn run(cli: Cli) -> Result<u8, CliError> {
         }
         Command::Scval { value } => {
             let value = read_value(value)?;
-            let decoded = xdr::inspect_scval_base64(&value).map_err(runtime)?;
-            print_value(format, &xdr::summary("scval", &decoded));
+            let decoded =
+                xdr::inspect_scval_base64_with_options(&value, options).map_err(runtime)?;
+            print_value(format, &decoded);
             Ok(EXIT_SUCCESS)
         }
         Command::Envelope { value } => {
             let value = read_value(value)?;
-            let decoded = xdr::inspect_envelope_base64(&value).map_err(runtime)?;
-            print_value(format, &xdr::summary("transaction_envelope", &decoded));
+            let decoded =
+                xdr::inspect_envelope_base64_with_options(&value, options).map_err(runtime)?;
+            print_value(format, &decoded);
             Ok(EXIT_SUCCESS)
         }
         Command::Event { value } => {
             let value = read_value(value)?;
-            let decoded = xdr::inspect_event_base64(&value).map_err(runtime)?;
-            print_value(format, &xdr::summary("contract_event", &decoded));
+            let decoded =
+                xdr::inspect_event_base64_with_options(&value, options).map_err(runtime)?;
+            print_value(format, &decoded);
             Ok(EXIT_SUCCESS)
         }
         Command::InspectWasm { path } => {

crates/devkit-cli/tests/xdr_schema.rs

@@ -0,0 +1,39 @@
+use std::process::{Command, Output};
+
+fn run_cli(args: &[&str]) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_stellar-foundry"))
+        .args(args)
+        .output()
+        .expect("run CLI")
+}
+
+#[test]
+fn scval_json_output_is_versioned() {
+    let output = run_cli(&["--format", "json", "scval", "AAAAAwAAACo="]);
+    assert!(
+        output.status.success(),
+        "CLI failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let value: serde_json::Value =
+        serde_json::from_slice(&output.stdout).expect("valid JSON output");
+    assert_eq!(value["schema_version"], "1.0");
+    assert_eq!(value["kind"], "scval");
+    assert_eq!(value["value"]["u32"], 42);
+    assert!(value.get("raw_xdr").is_none());
+}
+
+#[test]
+fn raw_flag_echoes_the_base64_input() {
+    let output = run_cli(&["--format", "json", "--raw", "scval", "AAAAAwAAACo="]);
+    assert!(
+        output.status.success(),
+        "CLI failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let value: serde_json::Value =
+        serde_json::from_slice(&output.stdout).expect("valid JSON output");
+    assert_eq!(value["schema_version"], "1.0");
+    assert_eq!(value["kind"], "scval");
+    assert_eq!(value["raw_xdr"], "AAAAAwAAACo=");
+}

crates/devkit-xdr/src/lib.rs

@@ -10,9 +10,25 @@
 
 use devkit_core::DevkitError;
 use serde::Serialize;
-use serde_json::{json, Value};
+use serde_json::Value;
 use stellar_xdr::{ContractEvent, Limits, ReadXdr, ScVal, TransactionEnvelope};
 
+/// Version of the decoded-XDR JSON schema emitted by this crate.
+///
+/// The schema covers the document envelope (`schema_version`, `kind`, `value`,
+/// and optional `raw_xdr`). See `docs/XDR.md` and `docs/SCVAL.md`.
+pub const XDR_JSON_SCHEMA_VERSION: &str = "1.0";
+
+/// Options controlling decoded-XDR output.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct DecodeOptions {
+    /// Include the canonical base64 XDR input as `raw_xdr`.
+    ///
+    /// Off by default so machine-readable output stays compact; the raw
+    /// encoding is always available behind this flag.
+    pub include_raw: bool,
+}
+
 /// Maximum recursion depth applied when decoding untrusted XDR.
 ///
 /// Bounds stack usage for deeply nested values.
@@ -46,24 +62,81 @@ pub struct StrkeyInfo {
     pub value: String,
 }
 
-/// Decodes a base64 `ScVal` and returns developer-friendly JSON.
+/// Build a versioned decoded-XDR document.
+///
+/// The envelope is the stable part of the schema:
+///
+/// ```json
+/// {
+///   "schema_version": "1.0",
+///   "kind": "scval",
+///   "value": { "...": "XDR-JSON payload" },
+///   "raw_xdr": "AAAAAwAAACo="
+/// }
+/// ```
+///
+/// `raw_xdr` is only present when [`DecodeOptions::include_raw`] is set.
+fn document(kind: &str, value: Value, input: &str, options: DecodeOptions) -> Value {
+    let mut object = serde_json::Map::new();
+    object.insert(
+        "schema_version".to_string(),
+        Value::String(XDR_JSON_SCHEMA_VERSION.to_string()),
+    );
+    object.insert("kind".to_string(), Value::String(kind.to_string()));
+    object.insert("value".to_string(), value);
+    if options.include_raw {
+        object.insert("raw_xdr".to_string(), Value::String(input.to_string()));
+    }
+    Value::Object(object)
+}
+
+/// Decodes a base64 `ScVal` and returns a versioned JSON document.
 pub fn inspect_scval_base64(input: &str) -> Result<Value, DevkitError> {
-    let value = ScVal::from_xdr_base64(input.trim(), limits()).map_err(DevkitError::decode)?;
-    serde_json::to_value(&value).map_err(DevkitError::decode)
+    inspect_scval_base64_with_options(input, DecodeOptions::default())
 }
 
-/// Decodes a base64 `TransactionEnvelope` and returns developer-friendly JSON.
+/// Decodes a base64 `ScVal` with explicit output options.
+pub fn inspect_scval_base64_with_options(
+    input: &str,
+    options: DecodeOptions,
+) -> Result<Value, DevkitError> {
+    let input = input.trim();
+    let value = ScVal::from_xdr_base64(input, limits()).map_err(DevkitError::decode)?;
+    let value = serde_json::to_value(&value).map_err(DevkitError::decode)?;
+    Ok(document("scval", value, input, options))
+}
+
+/// Decodes a base64 `TransactionEnvelope` and returns a versioned JSON document.
 pub fn inspect_envelope_base64(input: &str) -> Result<Value, DevkitError> {
-    let value = TransactionEnvelope::from_xdr_base64(input.trim(), limits())
-        .map_err(DevkitError::decode)?;
-    serde_json::to_value(&value).map_err(DevkitError::decode)
+    inspect_envelope_base64_with_options(input, DecodeOptions::default())
 }
 
-/// Decodes a base64 `ContractEvent` and returns developer-friendly JSON.
-pub fn inspect_event_base64(input: &str) -> Result<Value, DevkitError> {
+/// Decodes a base64 `TransactionEnvelope` with explicit output options.
+pub fn inspect_envelope_base64_with_options(
+    input: &str,
+    options: DecodeOptions,
+) -> Result<Value, DevkitError> {
+    let input = input.trim();
     let value =
-        ContractEvent::from_xdr_base64(input.trim(), limits()).map_err(DevkitError::decode)?;
-    serde_json::to_value(&value).map_err(DevkitError::decode)
+        TransactionEnvelope::from_xdr_base64(input, limits()).map_err(DevkitError::decode)?;
+    let value = serde_json::to_value(&value).map_err(DevkitError::decode)?;
+    Ok(document("transaction_envelope", value, input, options))
+}
+
+/// Decodes a base64 `ContractEvent` and returns a versioned JSON document.
+pub fn inspect_event_base64(input: &str) -> Result<Value, DevkitError> {
+    inspect_event_base64_with_options(input, DecodeOptions::default())
+}
+
+/// Decodes a base64 `ContractEvent` with explicit output options.
+pub fn inspect_event_base64_with_options(
+    input: &str,
+    options: DecodeOptions,
+) -> Result<Value, DevkitError> {
+    let input = input.trim();
+    let value = ContractEvent::from_xdr_base64(input, limits()).map_err(DevkitError::decode)?;
+    let value = serde_json::to_value(&value).map_err(DevkitError::decode)?;
+    Ok(document("contract_event", value, input, options))
 }
 
 /// Classifies a Stellar strkey.
@@ -85,9 +158,12 @@ pub fn describe_strkey(input: &str) -> Result<StrkeyInfo, DevkitError> {
     })
 }
 
-/// Builds a compact summary object for a decoded value, used by the CLI.
+/// Builds a versioned document for an already-decoded value.
+///
+/// Prefer the `inspect_*` functions, which decode under bounded limits. This
+/// helper remains for callers that already hold a decoded value.
 pub fn summary(kind: &str, value: &Value) -> Value {
-    json!({ "kind": kind, "value": value })
+    document(kind, value.clone(), "", DecodeOptions::default())
 }
 
 #[cfg(test)]
@@ -103,10 +179,38 @@ mod tests {
     fn decodes_scval_u32_roundtrip() {
         let encoded = roundtrip_scval(&ScVal::U32(42));
         let decoded = inspect_scval_base64(&encoded).unwrap();
+        assert_eq!(decoded["schema_version"], XDR_JSON_SCHEMA_VERSION);
+        assert_eq!(decoded["kind"], "scval");
+        assert!(decoded.get("value").is_some(), "missing value: {decoded}");
         let text = serde_json::to_string(&decoded).unwrap();
         assert!(text.contains("42"), "unexpected json: {text}");
     }
 
+    #[test]
+    fn raw_xdr_is_opt_in_and_preserved_verbatim() {
+        let encoded = roundtrip_scval(&ScVal::U32(7));
+        let default = inspect_scval_base64(&encoded).unwrap();
+        assert!(default.get("raw_xdr").is_none());
+
+        let with_raw = inspect_scval_base64_with_options(
+            &format!("  {encoded}\n"),
+            DecodeOptions { include_raw: true },
+        )
+        .unwrap();
+        assert_eq!(with_raw["raw_xdr"], encoded);
+        assert_eq!(with_raw["schema_version"], XDR_JSON_SCHEMA_VERSION);
+    }
+
+    #[test]
+    fn summary_uses_the_versioned_envelope() {
+        let value = serde_json::json!({ "u32": 1 });
+        let summary = summary("scval", &value);
+        assert_eq!(summary["schema_version"], XDR_JSON_SCHEMA_VERSION);
+        assert_eq!(summary["kind"], "scval");
+        assert_eq!(summary["value"], value);
+        assert!(summary.get("raw_xdr").is_none());
+    }
+
     #[test]
     fn decodes_scval_bool_roundtrip() {
         let encoded = roundtrip_scval(&ScVal::Bool(true));