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.