Skip to content

feat: extract lightweight serialization component from clarity crate #6247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

parsaaba
Copy link

@parsaaba parsaaba commented Jul 2, 2025

Fixes #6236

Problem:

  • The clarity crate included the full Clarity VM with heavy dependencies like rusqlite
  • Downstream crates needed to compile the entire VM just to serialize/deserialize Clarity values
  • This made it difficult to build lightweight applications that only needed serialization

Solution:

  • Created new clarity-serialization crate with minimal dependencies
  • Extracted core serialization types and traits from the main clarity crate
  • Maintained full API compatibility for existing code

Changes:

  • Add new clarity-serialization crate with lightweight dependencies
  • Extract Value enum and all supporting types (TupleData, ListData, etc.)
  • Extract ClaritySerializable/ClarityDeserializable traits and serialization logic
  • Extract core representations (ClarityName, ContractName, QualifiedContractIdentifier)
  • Add comprehensive error handling and validation
  • Update main clarity crate to depend on and re-export from clarity-serialization
  • Add workspace member for new crate
  • Include working example demonstrating usage

Benefits:

  • Downstream applications can serialize Clarity values without heavy VM dependencies
  • Faster compilation for lightweight use cases
  • Better separation of concerns between serialization and VM logic
  • Maintains backwards compatibility

Description

Applicable issues

  • fixes #

Additional info (benefits, drawbacks, caveats)

Checklist

  • Test coverage for new or modified code paths
  • Changelog is updated
  • Required documentation changes (e.g., docs/rpc/openapi.yaml and rpc-endpoints.md for v2 endpoints, event-dispatcher.md for new events)
  • New clarity functions have corresponding PR in clarity-benchmarking repo
  • New integration test(s) added to bitcoin-tests.yml

Fixes stacks-network#6236

Problem:
- The clarity crate included the full Clarity VM with heavy dependencies like rusqlite
- Downstream crates needed to compile the entire VM just to serialize/deserialize Clarity values
- This made it difficult to build lightweight applications that only needed serialization

Solution:
- Created new `clarity-serialization` crate with minimal dependencies
- Extracted core serialization types and traits from the main clarity crate
- Maintained full API compatibility for existing code

Changes:
- Add new `clarity-serialization` crate with lightweight dependencies
- Extract Value enum and all supporting types (TupleData, ListData, etc.)
- Extract ClaritySerializable/ClarityDeserializable traits and serialization logic
- Extract core representations (ClarityName, ContractName, QualifiedContractIdentifier)
- Add comprehensive error handling and validation
- Update main clarity crate to depend on and re-export from clarity-serialization
- Add workspace member for new crate
- Include working example demonstrating usage

Benefits:
- Downstream applications can serialize Clarity values without heavy VM dependencies
- Faster compilation for lightweight use cases
- Better separation of concerns between serialization and VM logic
- Maintains backwards compatibility

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@parsaaba parsaaba requested review from a team as code owners July 2, 2025 20:34
@CLAassistant
Copy link

CLAassistant commented Jul 2, 2025

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Refactor clarity to enable lightweight serialization crate
2 participants