Skip to main content

Crate personaldb_protocol

Crate personaldb_protocol 

Source
Expand description

§personaldb-protocol

personaldb-protocol is the small, implementation-independent contract shared by PersonalDB clients, projection builders, and server witnesses.

§Included contracts

  • Typed database identifiers, SHA-256 digests, group kinds, and state commitments.
  • Domain-separated Ed25519 envelopes and purpose-, scope-, generation-, status-, and log-bound trust policy.
  • Commit certificates, committed heads, signed group descriptors, and signed projection derivations.
  • Catch-up request and frame types, snapshot request and frame types, signed snapshot target manifests, and watch contracts.
  • Protocol bounds for chunks, entries, and catch-up pages.
  • Storage-independent authenticated-state primitives that reproduce PersonalDB’s canonical row, table, and database roots.

It deliberately does not provide a database, SQLite access, schemas, RPC clients, object storage, key custody, authorisation decisions, or a background runtime. Implementations remain responsible for authenticating callers, admitting transitions, persisting protocol objects, and enforcing stream state machines.

§Canonical projection delivery

Signed durable objects expose encode_deterministic and decode_canonical. Canonical decoders decode, validate, deterministically re-encode, and compare the exact input bytes. Unknown fields, duplicate scalar fields, reordered fields, non-minimal varints, malformed nested signatures, and other alternate protobuf encodings therefore fail closed.

Requests and watch notices are transport contracts rather than signed durable objects. A transport maps them to its authenticated HTTP, gRPC, or in-process API. Catch-up and snapshot frames are canonical protobuf records and keep signed evidence opaque until its own strict decoder has accepted it.

§Authenticated state

CanonicalStateValueV1 has the same externally tagged JSON representation as PersonalDB’s committed values. Primary-key values must be supplied in declared primary-key order. Stored values must be supplied in managed-schema column order.

The exported primitives implement this exact sequence:

  1. Encode the primary-key value array as compact JSON.
  2. Hash the row key and stored row with their PersonalDB JSON domains.
  3. Select one of 256 leaves from the first row-key hash byte.
  4. XOR row hashes in each leaf and bind the accumulator plus row count.
  5. Build the fixed-depth eight-level sparse table Merkle tree.
  6. Bind all writable managed table roots, ordered by table name, into the database state root.

The functions are independent of SQLite and storage layout. A server can retain leaf accumulators and nodes in any transactional store, while a client can recompute the same root from projected rows.

§0.2 compatibility

Version 0.2.0 is an intentional clean break from 0.1.0. Commitment fields now use DatabaseId, Sha256Digest, and DatabaseGroupKind directly, matching the canonical projection protocol in private PersonalDB commit 276515e624e91d3d0ac9f438d7d3a940ddf2ddb4. There is no raw-field compatibility facade or dual wire version.

Signing, projection, sync, snapshot, and authenticated-state encodings are covered by fixed vectors and adversarial canonicality tests.

§License

Apache-2.0.

Structs§

AuthenticatedRowV1
One committed managed row, independent of any storage engine.
CanonicalPrimaryKeyV1
Canonical JSON text for a row’s ordered primary-key values.
CommitCertificateV2
CommittedHeadV2
DatabaseId
A stable PersonalDB database identifier.
DescribeGroupRequest
Ed25519ProtocolSigner
Ed25519PublicKey
Ed25519Signature
GroupDescriptor
HeadNotice
KeyGeneration
KeyId
KeyTrustPolicy
LogEntryCoreV2
MerkleLeafAccumulatorV2
XOR accumulator and row count for one of the 256 sparse table leaves.
PersonalDbCatchUpRequestV1
PersonalDbSnapshotRequestV1
ProjectionDefinitionV1
A deliberately bounded, immutable PersonalDB projection template.
ProjectionDerivationV1
Deterministic evidence binding source heads and a projection transition.
PublicKeyEnvelopeV1
Canonical deterministic-protobuf Ed25519 public-key envelope.
PublicKeyTrustRecord
PublicKeyTrustStore
Sha256Digest
SignatureEnvelopeV1
Canonical deterministic-protobuf signature envelope.
SignatureMetadata
SignatureScope
SignedProjectionDerivationV1
Projection derivation carrying the sole admitted projection-builder signature.
SignedSnapshotTargetManifestV1
SigningPreimage
SnapshotChunkV1
SnapshotEndV1
SnapshotHeaderV1
SnapshotTargetManifestV1
SourceHeadV1
StateCommitmentV1
SyncEndV1
SyncEntryChunkV1
SyncEntryEndV1
SyncEntryStartV1
SyncErrorV1
SyncHeaderV1
TableMerkleNodeV2
A materialized sparse-Merkle node and the number of rows below it.
TableStateRootV2
Final authenticated state for one writable managed table.
UnsignedCommitCertificateV2
UnsignedCommittedHeadV2
UnsignedGroupDescriptorV1
VerifiedSignature
WatchRequest

Enums§

AuthenticatedStateError
CanonicalStateValueV1
Storage-neutral values in the exact externally-tagged JSON representation used by PersonalDB’s authenticated row algorithm.
DatabaseGroupKind
HashAlgorithm
PersonalDbSnapshotFrameV1
PersonalDbSyncFrameV1
ProjectionDefinitionModeV1
ProjectionProtocolError
ProtocolSecurityProfile
PublicKeyStatus
SignatureAlgorithm
SignatureDomain
SignatureError
SignaturePurpose
SigningPayload
SnapshotCompressionV1
SyncErrorCodeV1

Constants§

DATABASE_ROOT_DOMAIN_V1
ED25519_PUBLIC_KEY_LENGTH
ED25519_SIGNATURE_LENGTH
EMPTY_TABLE_DOMAIN_V1
GROUP_DESCRIPTOR_FORMAT_VERSION_V1
MAX_PROTOCOL_ID_BYTES
MAX_SYNC_CHUNK_BYTES
MAX_SYNC_ENTRY_BYTES
MAX_SYNC_PAGE_BYTES
MAX_SYNC_PAGE_ENTRIES
MERKLE_LEAF_DOMAIN_V2
MERKLE_NODE_DOMAIN_V2
PROJECTION_DEFINITION_FORMAT_VERSION_V1
PROJECTION_DERIVATION_FORMAT_VERSION_V1
PROTOCOL_EVIDENCE_FORMAT_VERSION_V2
PUBLIC_KEY_ENVELOPE_FORMAT_VERSION_V1
PUBLIC_KEY_TRUST_RECORD_FORMAT_VERSION_V1
ROW_KEY_DOMAIN_V1
ROW_STATE_DOMAIN_V1
SHA256_DIGEST_LENGTH
SIGNATURE_ENVELOPE_FORMAT_VERSION_V1
STATE_COMMITMENT_FORMAT_VERSION_V1
SYNC_FORMAT_VERSION_V1
TABLE_MERKLE_DEPTH_V2
The fixed table tree has one leaf for each possible first byte of a row-key hash.

Traits§

ProtocolSignable
Implement this on typed canonical protocol objects, never on an arbitrary-byte RPC request.
ProtocolSignatureVerifier
ProtocolSigner

Functions§

canonical_primary_key_json_v1
Returns the exact compact JSON text committed as a primary-key string.
database_state_root_v1
Computes the database root over all writable managed table roots.
ed25519_public_key_envelope_v1_bytes
empty_table_state_root_v1
Root used for a writable managed table with no committed rows.
merkle_leaf_bucket_v2
Selects one of 256 leaves from the first byte of the row-key SHA-256 digest.
merkle_leaf_node_v2
Materializes a non-empty sparse-Merkle leaf.
merkle_parent_node_v2
Materializes one internal sparse-Merkle node.
row_key_hash_v1
Hashes a table name and canonical primary-key JSON into the row-key digest.
row_state_hash_v1
Hashes the exact committed stored values for one managed row.
signing_preimage
Builds the sole PersonalDB signing preimage from canonical bytes or their exact SHA-256.
table_state_root_v2
Recomputes a table root from storage-neutral committed rows.

Type Aliases§

LogIndex
The zero-based position of an operation in a PersonalDB log.