Ledger

Note

See the Ledger and Snapshots section to find out more about how ledger files are generated by CCF nodes and how they should be managed by operators.

The entire service and application state is contained in the ledger (including both governance and application transactions). The ledger contains regular signature transactions (public:ccf.internal.signatures map) which sign the root of the Merkle Tree at the time the signature transaction is emitted.

Tip

Use the read_ledger.py utility available as part of the Python Library to read the public content of a CCF ledger.

Ledger Format

The ledger is split into multiple files (or chunks). Each ledger file starts with an 8-byte offset pointing to the end of file where a vector of positions is stored for fast fetching of transactions (only set when a file is complete, internal use only).

The serialised transactions follow the 8-byte offset, as described in Transaction Format.

Note

A complete ledger file always ends on a signature transaction.

Transaction Format

The following table describes the structure of a serialised transaction as it is stored in the ledger.

Note

These serialised transactions in CCF currently describes only the final write set rather than the internal execution path of a transaction; writes are reordered, only the final writes are present, and reads are omitted (read count will be 0).

	Field Type			Description
Header	Transaction Header			- Version (1 byte) - Flags (1 byte) - Entry size (6 bytes)
	AES GCM Header			IV and tag fields required to decrypt and verify integrity
	uint64_t			Length of serialised public domain
Public Domain	ccf::kv::EntryType			Snapshot, or a WriteSet variant
	ccf::kv::Version			Transaction version
	ccf::crypto::Sha256Hash			User-defined claims digest, when entry type is WriteSetWith.*Claims
	ccf::crypto::Sha256Hash			Commit evidence digest, when entry type is WriteSetWithCommitEvidence.*
	ccf::kv::Version			Unused, reserved for compatibility
	Repeating [0..n]			With n the number of maps in the transaction
		std::string		Name of the serialised ccf::kv::Map
		ccf::kv::Version		Read version
		uint64_t		Read count
		Repeating [0..read count]
			uint64_t K Ver	Key length Key Version
		uint64_t		Write count
		Repeating [0..write count]
			uint64_t K uint64_t V	Key length Key Value length Value
		uint64_t		Remove count
		Repeating [0..remove count]
			uint64_t K	Key length Key
Private Domain	Optional | Encrypted serialised private domain blob.

Transaction Encryption

Each entry in the ledger corresponds to a transaction committed by the primary node.

When a transaction is committed, each Store::Map containing writes is serialised in different security domains (i.e. public or private), based on the name of the Map when it was created (default is private). A public Store::Map (i.e. one whose name starts with “public:”) is serialised and stored in the ledger as plaintext while a private Store::Map is serialised and encrypted before being stored.

Ledger entries are integrity-protected and encrypted using a symmetric key shared by all trusted nodes (see Cryptography). This key is kept secure inside each enclave. See Rekeying Ledger for details on how members can rotate the ledger encryption key.

Note that even if a transaction only writes to a private Store::Map, unencrypted information such as the sequence number is always present in the serialised entry.