Fluentbase Codec

A lightweight, no-std compatible codec library optimized for random reads. While similar to Solidity ABI encoding, it introduces several optimizations and additional features for efficient data access and nested structures.

Key Features

No-std compatible
Configurable byte order and alignment
Support for Solidity ABI compatibility mode
Random access to first-level information without full decoding
Support for recursive encoding of nested structures
Derive macro support for custom types

Encoding Modes

The library supports two main encoding modes:

CompactABI Mode

CompactABI::encode(&value, &mut buf, 0)

Little-endian byte order
4-byte alignment

Dynamic structure encoding:

Header:
  - length (u32): number of elements
  - offset (u32): position in the buffer
  - size (u32): total number of encoded bytes
Body:
  - encoded elements

SolidityABI Mode

SolidityABI::encode(&value, &mut buf, 0)

Big-endian byte order
32-byte alignment (Ethereum compatible)

Dynamic structure encoding:

Header:
  - offset (u32): position in the structure
Body:
  - length (u32): number of elements
  - encoded elements

Type System

Primitive Types

Primitives are encoded without additional metadata, providing zero-cost encoding:

Integer types: u8, i8, u16, i16, u32, i32, u64, i64
Boolean type: bool
Unit type: ()
Static arrays: [T; N]
Tuples: (T,), (T1, T2), etc.
Option type: Option<T>
Large integers: U128, U256, I128, I256 (from alloy_primitives)

Non-Primitive Types

These types require additional metadata for encoding:

Vec<T>: Dynamic array of encodable elements
HashMap<K,V>: Hash map with encodable keys and values
HashSet<T>: Hash set with encodable elements

For dynamic types, the codec stores metadata that enables partial reading. For example:

Vectors store offset and length information
HashMaps store separate metadata for keys and values, allowing independent access

Usage Examples

Basic Structure

use fluentbase_codec::{Codec, CompactABI};
use bytes::BytesMut;

#[derive(Codec)]
struct Point {
    x: u32,
    y: u32,
}

// Encoding
let point = Point { x: 10, y: 20 };
let mut buf = BytesMut::new();
CompactABI::encode(&point, &mut buf, 0).unwrap();

// Decoding
let decoded: Point = CompactABI::decode(&buf, 0).unwrap();

Dynamic Array Example

// Vector encoding with metadata
let numbers = vec![1, 2, 3];

// CompactABI encoding (with full metadata)
let mut fluent_buf = BytesMut::new();
CompactABI::encode(&numbers, &mut fluent_buf, 0).unwrap();
// Format: [length:3][offset:12][size:12][1][2][3]

// SolidityABI encoding
let mut solidity_buf = BytesMut::new();
SolidityABI::encode(&numbers, &mut solidity_buf, 0).unwrap();
// Format: [offset:32][length:3][1][2][3]

Important Notes

Determinism

The encoded binary is not deterministic and should only be used for parameter passing. The encoding order of non-primitive fields affects the data layout after the header, though decoding will produce the same result regardless of encoding order.

Order Sensitivity

The order of encoding operations is significant, especially for non-primitive types, as it affects the final binary layout.

Installation

Add to your Cargo.toml:

[dependencies]
fluentbase-codec = "0.1.0"

License

MIT or Apache-2.0

fluentbase-codec 1.1.1