add clarity-serialization

Author: Jiloc

.cargo/config.toml

@@ -1,7 +1,7 @@
 [alias]
 stacks-node = "run --package stacks-node --"
 fmt-stacks = "fmt -- --config group_imports=StdExternalCrate,imports_granularity=Module"
-clippy-stacks = "clippy -p stx-genesis -p libstackerdb -p stacks-signer -p pox-locking -p clarity -p libsigner -p stacks-common --no-deps --tests --all-features -- -D warnings"
+clippy-stacks = "clippy -p stx-genesis -p libstackerdb -p stacks-signer -p pox-locking -p clarity-serialization -p clarity -p libsigner -p stacks-common --no-deps --tests --all-features -- -D warnings"
 clippy-stackslib = "clippy -p stackslib --no-deps -- -Aclippy::all -Wclippy::indexing_slicing"
 
 # Uncomment to improve performance slightly, at the cost of portability

Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "stackslib",
     "stacks-common",
     "pox-locking",
+    "clarity-serialization",
     "clarity",
     "stx-genesis",
     "libstackerdb",

Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "clarity-serialization"
+version = "0.0.1"
+edition = "2024"
+description = "Serialization and deserialization for Stacks Clarity smart contract language types."
+license = "GPLv3"
+homepage = "https://github.com/stacks-network/stacks-core"
+repository = "https://github.com/stacks-network/stacks-core"
+keywords = [ "stacks", "stx", "bitcoin", "crypto", "blockstack", "decentralized", "dapps", "blockchain" ]
+readme = "README.md"
+
+[dependencies]
+hashbrown = { workspace = true }
+lazy_static = { workspace = true }
+regex = { version = "1", default-features = false }
+serde = { workspace = true }
+serde_derive = { workspace = true }
+slog = { workspace = true }
+stacks_common = { package = "stacks-common", path = "../stacks-common", default-features = false }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+mutants = "0.0.3"
+
+[features]
+default = []
+testing = []
+slog_json = ["stacks_common/slog_json"]
+
+# Wasm-specific features for easier configuration
+wasm-web = ["stacks_common/wasm-web"]
+wasm-deterministic = ["stacks_common/wasm-deterministic"]

clarity-serialization/Cargo.toml

@@ -0,0 +1,137 @@
+# Clarity Serialization (`clarity-serialization`)
+
+[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+A Rust crate for representing, serializing, and deserializing data types from the Stacks Clarity smart contract language.
+
+## Overview
+
+This crate provides the core components for working with Clarity data structures in Rust. It defines canonical Rust types for every Clarity value (e.g., `Value`, `TypeSignature`, `PrincipalData`) and implements the consensus-critical binary serialization and deserialization format used by the Stacks blockchain.
+
+## Key Features
+
+*   **Canonical Data Structures**: Rust representations for all Clarity types, including `int`, `uint`, `bool`, `principal`, `optional`, `response`, `tuple`, `list`, `buffer`, and strings.
+*   **Consensus-Compatible Binary Codec**: Implements the binary serialization and deserialization format required by the Stacks blockchain.
+*   **Type Safety**: Includes type-checking logic (`admits`, `least_supertype`) for validating values against type signatures.
+
+## Quick Start: Usage Examples
+
+### Example 1: Serializing a Clarity Value to Hex
+
+This example demonstrates how to construct a complex Clarity `(tuple)` and serialize it to its hexadecimal string representation, which is suitable for use as a transaction argument.
+
+```rust
+use clarity_serialization::types::{Value, TupleData, PrincipalData};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // 1. Construct the individual values that will go into our tuple.
+    let id = Value::UInt(101);
+    let owner = Value::Principal(
+        PrincipalData::parse("SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G")?
+    );
+    let metadata = Value::some(
+        Value::buff_from(vec![0xde, 0xad, 0xbe, 0xef])?
+    )?;
+
+    // 2. Create a vec of name-value pairs for the tuple.
+    let tuple_fields = vec![
+        ("id".into(), id),
+        ("owner".into(), owner),
+        ("metadata".into(), metadata),
+    ];
+
+    // 3. Construct the tuple value.
+    let my_tuple = Value::from(TupleData::from_data(tuple_fields)?);
+
+    // 4. Serialize the tuple to its consensus-cricital hex string.
+    let hex_string = my_tuple.serialize_to_hex()?;
+
+    println!("Clarity Tuple: {}", my_tuple);
+    println!("Serialized Hex: {}", hex_string);
+
+    // The output `hex_string` can now be used in a contract-call transaction.
+    assert_eq!(
+        hex_string,
+        "0c000000030269640100000000000000000000000000000065086d657461646174610a0200000004deadbeef056f776e65720514a46ff88886c2ef9762d970b4d2c63678835bd39d"
+    );
+
+    Ok(())
+}
+```
+
+### Example 2: Deserializing a Clarity Value from Hex
+
+This example shows the reverse process: taking a hex string and deserializing it into a structured `Value` object, while validating it against an expected type.
+
+```rust
+use clarity_serialization::types::{Value, TypeSignature};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let hex_string = "0c000000030269640100000000000000000000000000000065086d657461646174610a0200000004deadbeef056f776e65720514a46ff88886c2ef9762d970b4d2c63678835bd39d";
+
+    // 1. First, let's deserialize without a type for inspection.
+    // NOTE: This is not recommended for production use with data from untrusted sources.
+    let untyped_value = Value::try_deserialize_hex_untyped(hex_string)?;
+    println!("Deserialized (untyped): {:?}", untyped_value);
+
+    // 2. For robust deserialization, we should define the expected type.
+    // This can be derived from the untyped value or known from a contract's interface.
+    let expected_type = TypeSignature::type_of(&untyped_value)?;
+    println!("Inferred Type Signature: {}", expected_type);
+
+    // 3. Deserialize again, this time enforcing the type signature.
+    // The `sanitize` flag should be `true` when reading values from the DB
+    // that were stored before Stacks 2.4. For new values, it can be `false`.
+    let typed_value = Value::try_deserialize_hex(hex_string, &expected_type, false)?;
+
+    // 4. Now we can safely access the tuple's fields.
+    let tuple_data = typed_value.expect_tuple()?;
+    let id = tuple_data.get("id")?.clone().expect_u128()?;
+    let owner = tuple_data.get("owner")?.clone().expect_principal()?;
+
+    println!("Successfully deserialized and validated!");
+    println!("ID: {}", id);
+    println!("Owner: {}", owner);
+
+    Ok(())
+}
+```
+
+## Clarity Value Binary Format
+
+The crate implements the standard binary format for Clarity values. At a high level, every value is encoded as: `[Type Prefix Byte] + [Payload]`.
+
+| Type Prefix (Hex) | Clarity Type      | Payload Description                                                              |
+| ----------------- | ----------------- | -------------------------------------------------------------------------------- |
+| `0x00`            | `int`             | 16-byte big-endian signed integer.                                               |
+| `0x01`            | `uint`            | 16-byte big-endian unsigned integer.                                             |
+| `0x02`            | `(buff L)`        | 4-byte big-endian length `L`, followed by `L` raw bytes.                         |
+| `0x03`            | `true`            | No payload.                                                                      |
+| `0x04`            | `false`           | No payload.                                                                      |
+| `0x05`            | `principal` (Std) | 1-byte version, followed by 20-byte HASH160.                                     |
+| `0x06`            | `principal` (Cont)| Serialized Contract Principal (issuer) + 1-byte length-prefixed contract name.   |
+| `0x07`            | `(ok V)`          | The serialized inner value `V`.                                                  |
+| `0x08`            | `(err V)`         | The serialized inner value `V`.                                                  |
+| `0x09`            | `none`            | No payload.                                                                      |
+| `0x0a`            | `(some V)`        | The serialized inner value `V`.                                                  |
+| `0x0b`            | `(list ...)`      | 4-byte big-endian element count, followed by each serialized element.            |
+| `0x0c`            | `(tuple ...)`     | 4-byte big-endian entry count, followed by each serialized `(name, value)` pair. |
+| `0x0d`            | `(string-ascii L)`| 4-byte big-endian length `L`, followed by `L` ASCII bytes.                       |
+| `0x0e`            | `(string-utf8 L)` | 4-byte big-endian byte-length `L`, followed by `L` UTF8 bytes.                   |
+
+## Crate Features
+
+This crate is designed to be minimal by default. Optional functionality is available via feature flags:
+
+*   `developer-mode`: Enables additional debugging and logging information useful during development.
+*   `testing`: Enables helper functions and data structures used exclusively for unit and integration testing.
+*   `slog_json`: Integrates with `slog` for structured JSON logging.
+*   `wasm-web` / `wasm-deterministic`: Enables builds for WebAssembly environments with different determinism guarantees.
+
+## Contributing
+
+Contributions are welcome! This crate is part of the `stacks-core` monorepo. Please see the [main repository's contributing guidelines](https://github.com/stacks-network/stacks-core/blob/master/CONTRIBUTING.md) for more details on the development process.
+
+## License
+
+This project is licensed under the **GNU General Public License v3.0** ([GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)). See the `LICENSE` file for details.

clarity-serialization/README.md

@@ -0,0 +1,107 @@
+use std::io;
+
+use thiserror::Error;
+
+use crate::types::{TupleTypeSignature, TypeSignature, Value};
+
+/// The primary error type for the `clarity-codec` crate.
+///
+/// It represents all possible failures that can occur when encoding, decoding,
+/// or validating the structure and types of a Clarity value.
+#[derive(Error, Debug)]
+pub enum CodecError {
+    #[error("I/O error during (de)serialization: {0}")]
+    Io(#[from] io::Error),
+
+    #[error("Serialization error caused by IO: {0}")]
+    Serialization(String),
+
+    #[error("Deserialization failed: {0}")]
+    Deserialization(String),
+
+    #[error("Deserialization expected the type of the input to be: {0}")]
+    DeserializeExpected(Box<TypeSignature>),
+
+    #[error("The serializer handled an input in an unexpected way")]
+    UnexpectedSerialization,
+
+    #[error("Deserialization finished but there were leftover bytes in the buffer")]
+    LeftoverBytesInDeserialization,
+
+    #[error("Parse error: {0}")]
+    ParseError(String),
+
+    #[error("Bad type construction.")]
+    BadTypeConstruction,
+
+    // --- Structural and Size Errors ---
+    #[error("A value being constructed is larger than the 1MB Clarity limit")]
+    ValueTooLarge,
+
+    #[error("A value is out of its prescribed bounds")]
+    ValueOutOfBounds,
+
+    #[error("A type signature is deeper than the 32-level Clarity limit")]
+    TypeSignatureTooDeep,
+
+    #[error("The supertype of two types is too large to be represented")]
+    SupertypeTooLarge,
+
+    #[error("Empty tuples are not allowed")]
+    EmptyTuplesNotAllowed,
+
+    #[error("Failed to construct a tuple with the given type")]
+    FailureConstructingTupleWithType,
+
+    #[error("Failed to construct a list with the given type")]
+    FailureConstructingListWithType,
+
+    #[error("All elements in a list must have a compatible supertype")]
+    ListTypesMustMatch,
+
+    // --- Type Mismatch and Semantic Errors ---
+    #[error("Expected a value of type '{expected}', but found a value of type '{found}'")]
+    TypeError {
+        expected: Box<TypeSignature>,
+        found: Box<TypeSignature>,
+    },
+
+    #[error("Expected a value of type '{expected}', but found the value '{found}'")]
+    TypeValueError {
+        expected: Box<TypeSignature>,
+        found: Box<Value>,
+    },
+
+    #[error("could not determine the input type for the serialization function")]
+    CouldNotDetermineSerializationType,
+
+    #[error("type of expression cannot be determined")]
+    CouldNotDetermineType,
+
+    #[error("Deserialization expected a value of type '{0}', but the data did not match")]
+    DeserializeWrongType(Box<TypeSignature>),
+
+    // --- Naming and Identifier Errors ---
+    #[error("Name '{0}' is already used in this tuple")]
+    NameAlreadyUsedInTuple(String),
+
+    #[error("Could not find field '{0}' in tuple '{1}'")]
+    NoSuchTupleField(String, TupleTypeSignature),
+
+    #[error("Failed to parse {0}: {1}")]
+    InvalidClarityName(&'static str, String),
+
+    #[error("Failed to parse {0}: {1}")]
+    InvalidContractName(&'static str, String),
+
+    // --- String/Buffer Content Errors ---
+    #[error("Invalid characters detected in string")]
+    InvalidStringCharacters,
+
+    #[error("Invalid UTF-8 encoding in string")]
+    InvalidUtf8Encoding,
+
+    // --- Catch-all for internal logic errors ---
+    #[error("An unexpected internal error occurred: {0}")]
+    Expect(String),
+}

clarity-serialization/src/errors.rs

@@ -0,0 +1,61 @@
+// Copyright (C) 2013-2020 Blockstack PBC, a public benefit corporation
+// Copyright (C) 2020 Stacks Open Internet Foundation
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+#[macro_use]
+extern crate serde_derive;
+
+#[macro_use]
+extern crate stacks_common;
+
+pub use stacks_common::{
+    codec, consts, impl_array_hexstring_fmt, impl_array_newtype, impl_byte_array_message_codec,
+    impl_byte_array_serde, types as stacks_types, util,
+};
+
+pub mod errors;
+pub mod representations;
+pub mod types;
+
+#[cfg(any(test, feature = "testing"))]
+pub mod tests;
+
+// set via _compile-time_ envars
+const GIT_BRANCH: Option<&'static str> = option_env!("GIT_BRANCH");
+const GIT_COMMIT: Option<&'static str> = option_env!("GIT_COMMIT");
+const GIT_TREE_CLEAN: Option<&'static str> = option_env!("GIT_TREE_CLEAN");
+
+#[cfg(debug_assertions)]
+const BUILD_TYPE: &str = "debug";
+#[cfg(not(debug_assertions))]
+const BUILD_TYPE: &str = "release";
+
+pub fn version_string(pkg_name: &str, pkg_version: &str) -> String {
+    let git_branch = GIT_BRANCH.unwrap_or("");
+    let git_commit = GIT_COMMIT.unwrap_or("");
+    let git_tree_clean = GIT_TREE_CLEAN.unwrap_or("");
+
+    format!(
+        "{} {} ({}:{}{}, {} build, {} [{}])",
+        pkg_name,
+        pkg_version,
+        &git_branch,
+        git_commit,
+        git_tree_clean,
+        BUILD_TYPE,
+        std::env::consts::OS,
+        std::env::consts::ARCH
+    )
+}