Crate grc_20 

GRC-20 v2: Binary property graph format for decentralized knowledge networks.

This crate provides encoding, decoding, and validation for the GRC-20 v2 binary format as specified in the GRC-20 v2 Specification.

Overview

GRC-20 is a property graph format designed for:

• Event-sourced data: All state changes are expressed as operations
• Binary-first: Optimized for compressed wire size and decode speed
• Pluralistic: Multiple spaces can hold conflicting views

Quick Start

use std::borrow::Cow;
use grc_20::{Edit, Op, CreateEntity, PropertyValue, Value, DataType};
use grc_20::codec::{encode_edit, decode_edit};
use grc_20::genesis::properties;

// Create an edit with an entity
let edit = Edit {
    id: [1u8; 16],
    name: Cow::Owned("My Edit".to_string()),
    authors: vec![[2u8; 16]],
    created_at: 1234567890,
    ops: vec![
        Op::CreateEntity(CreateEntity {
            id: [3u8; 16],
            values: vec![PropertyValue {
                property: properties::name(),
                value: Value::Text {
                    value: Cow::Owned("Alice".to_string()),
                    language: None,
                },
            }],
            context: None,
        }),
    ],
};

// Encode to binary
let bytes = encode_edit(&edit).unwrap();

// Decode back (zero-copy for uncompressed data)
let decoded = decode_edit(&bytes).unwrap();
assert_eq!(edit.id, decoded.id);

Modules

• model: Core data types (Entity, Relation, Value, Op, Edit)
• codec: Binary encoding/decoding with compression support
• validate: Semantic validation
• genesis: Well-known IDs from the Genesis Space
• error: Error types
• limits: Security limits for decoding

Security

The decoder is designed to safely handle untrusted input:

• All allocations are bounded by configurable limits
• Varints are limited to prevent overflow
• Invalid data is rejected with descriptive errors

Wire Format

Edits use a binary format with optional zstd compression:

• Uncompressed: GRC2 magic + version + data
• Compressed: GRC2Z magic + uncompressed size + zstd data

The decoder automatically detects and handles both formats.

Re-exports

pub use codec::decode_edit;

pub use codec::decompress;

pub use codec::encode_edit;

pub use codec::encode_edit_compressed;

pub use codec::encode_edit_compressed_with_options;

pub use codec::encode_edit_profiled;

pub use codec::encode_edit_with_options;

pub use codec::EncodeOptions;

pub use error::DecodeError;

pub use error::EncodeError;

pub use error::ValidationError;

pub use model::CreateEntity;

pub use model::CreateRelation;

pub use model::DataType;

pub use model::DecimalMantissa;

pub use model::DeleteEntity;

pub use model::DeleteRelation;

pub use model::DictionaryBuilder;

pub use model::Edit;

pub use model::EditBuilder;

pub use model::EmbeddingSubType;

pub use model::EntityBuilder;

pub use model::Id;

pub use model::Op;

pub use model::Property;

pub use model::PropertyValue;

pub use model::RelationBuilder;

pub use model::UnsetLanguage;

pub use model::UnsetRelationField;

pub use model::UnsetValue;

pub use model::UpdateEntity;

pub use model::UpdateEntityBuilder;

pub use model::UpdateRelation;

pub use model::Value;

pub use model::WireDictionaries;

pub use model::builder::UpdateRelationBuilder;

pub use model::id::derived_uuid;

pub use model::id::format_id;

pub use model::id::parse_id;

pub use model::id::text_value_id;

pub use model::id::value_id;

pub use model::id::NIL_ID;

pub use util::format_date_rfc3339;

pub use util::format_datetime_rfc3339;

pub use util::format_time_rfc3339;

pub use util::parse_date_rfc3339;

pub use util::parse_datetime_rfc3339;

pub use util::parse_time_rfc3339;

pub use util::DateTimeParseError;

pub use validate::validate_edit;

pub use validate::validate_position;

pub use validate::validate_value;

pub use validate::SchemaContext;

Modules

codec

Binary encoding/decoding for GRC-20.

error

Error types for GRC-20 encoding/decoding and validation.

genesis

Genesis Space well-known IDs.

limits

Security limits for GRC-20 encoding/decoding.

model

Data model types for GRC-20.

util

Utility modules for GRC-20.

validate

Semantic validation for GRC-20 edits.

Constants

SPEC_VERSION

GRC-20 spec version this crate implements.

VERSION

Crate version.