grc_20/
lib.rs

1//! GRC-20 v2: Binary property graph format for decentralized knowledge networks.
2//!
3//! This crate provides encoding, decoding, and validation for the GRC-20 v2
4//! binary format as specified in the GRC-20 v2 Specification.
5//!
6//! # Overview
7//!
8//! GRC-20 is a property graph format designed for:
9//! - **Event-sourced data**: All state changes are expressed as operations
10//! - **Binary-first**: Optimized for compressed wire size and decode speed
11//! - **Pluralistic**: Multiple spaces can hold conflicting views
12//!
13//! # Quick Start
14//!
15//! ```rust
16//! use std::borrow::Cow;
17//! use grc_20::{Edit, Op, CreateEntity, PropertyValue, Value, DataType};
18//! use grc_20::codec::{encode_edit, decode_edit};
19//! use grc_20::genesis::properties;
20//!
21//! // Create an edit with an entity
22//! let edit = Edit {
23//!     id: [1u8; 16],
24//!     name: Cow::Owned("My Edit".to_string()),
25//!     authors: vec![[2u8; 16]],
26//!     created_at: 1234567890,
27//!     ops: vec![
28//!         Op::CreateEntity(CreateEntity {
29//!             id: [3u8; 16],
30//!             values: vec![PropertyValue {
31//!                 property: properties::name(),
32//!                 value: Value::Text {
33//!                     value: Cow::Owned("Alice".to_string()),
34//!                     language: None,
35//!                 },
36//!             }],
37//!         }),
38//!     ],
39//! };
40//!
41//! // Encode to binary
42//! let bytes = encode_edit(&edit).unwrap();
43//!
44//! // Decode back (zero-copy for uncompressed data)
45//! let decoded = decode_edit(&bytes).unwrap();
46//! assert_eq!(edit.id, decoded.id);
47//! ```
48//!
49//! # Modules
50//!
51//! - [`model`]: Core data types (Entity, Relation, Value, Op, Edit)
52//! - [`codec`]: Binary encoding/decoding with compression support
53//! - [`validate`]: Semantic validation
54//! - [`genesis`]: Well-known IDs from the Genesis Space
55//! - [`error`]: Error types
56//! - [`limits`]: Security limits for decoding
57//!
58//! # Security
59//!
60//! The decoder is designed to safely handle untrusted input:
61//! - All allocations are bounded by configurable limits
62//! - Varints are limited to prevent overflow
63//! - Invalid data is rejected with descriptive errors
64//!
65//! # Wire Format
66//!
67//! Edits use a binary format with optional zstd compression:
68//! - Uncompressed: `GRC2` magic + version + data
69//! - Compressed: `GRC2Z` magic + uncompressed size + zstd data
70//!
71//! The decoder automatically detects and handles both formats.
72
73pub mod codec;
74pub mod error;
75pub mod genesis;
76pub mod limits;
77pub mod model;
78pub mod validate;
79
80// Re-export commonly used types at crate root
81pub use codec::{
82    decode_edit, decompress, encode_edit, encode_edit_compressed,
83    encode_edit_compressed_with_options, encode_edit_profiled, encode_edit_with_options,
84    EncodeOptions,
85};
86pub use error::{DecodeError, EncodeError, ValidationError};
87pub use model::{
88    CreateEntity, CreateRelation, DataType, DecimalMantissa, DeleteEntity,
89    DeleteRelation, DictionaryBuilder, Edit, EditBuilder, EmbeddingSubType, EntityBuilder, Id,
90    Op, Property, PropertyValue, RelationBuilder, UnsetLanguage, UnsetRelationField, UnsetValue,
91    UpdateEntity, UpdateEntityBuilder, UpdateRelation, Value, WireDictionaries,
92};
93pub use model::builder::UpdateRelationBuilder;
94pub use model::id::{derived_uuid, format_id, parse_id, text_value_id, value_id, NIL_ID};
95pub use validate::{validate_edit, validate_position, validate_value, SchemaContext};
96
97/// Crate version.
98pub const VERSION: &str = env!("CARGO_PKG_VERSION");
99
100/// GRC-20 spec version this crate implements.
101pub const SPEC_VERSION: &str = "0.17.0";
grc_20/lib.rs

grc_20/
lib.rs
