FAQ

Common questions about the protocol, identity, consensus, storage, and development.

Protocol

How is Makechain different from Git?

Git is local. Makechain orders and stores git-like operations (project creation, commits, ref updates, access control) as signed messages on a BFT consensus chain. Every operation has cryptographic attribution and global ordering.

What are 1P and 2P semantics?

1P (one-phase) — unilateral state changes with no paired undo. Includes FORK, PROJECT_METADATA, ACCOUNT_DATA, COMMIT_BUNDLE, and PROJECT_ARCHIVE.
2P (two-phase) — add/remove pairs on a set. Remove wins on tie. Used for projects, refs, collaborators, keys, and verifications.

See the state model for details.

How does CAS work for refs?

Ref updates include the expected current hash (old_hash) and a monotonic nonce. If the ref has moved, the update is rejected with RefCasMismatch.

What happens when a message fails execution?

Stages 1–5 of the submit pipeline reject synchronously on submit. Stage 6 (block execution) runs asynchronously — failed messages are silently dropped and the block proceeds without them.

What is a conflict key?

The tuple identifying which state slot a message targets. For example, (project_id, field) for PROJECT_METADATA. Messages with the same conflict key are resolved by LWW or CAS depending on the type.

Identity

What is a Make ID?

A uint64 account identifier assigned by the onchain registry. Every message references a mid identifying the acting account.

What are key scopes?

Scope	Permissions
OWNER	Full control: manage keys, remove projects, manage collaborators
SIGNING	Create projects, push commits, update refs, add verifications
AGENT	Automated actions, restricted to specific projects via `allowed_projects`

Scopes are hierarchical — higher scopes inherit all lower-scope permissions.

How does verification work?

You sign makechain:verify:<mid> with your external key and submit a VERIFICATION_ADD message. Supported address types:

ETH_ADDRESS — EIP-191 personal_sign recovery
SOL_ADDRESS — Ed25519 verification (address is the public key)

See identity for details.

Consensus

How fast is finality?

~200ms block time, ~300ms finality (2-chain rule).

Can I run a validator?

Currently devnet with a single validator. Multi-validator support is implemented (--bootstrapper and multi-participant flags). Public validator participation will open on testnet.

What consensus algorithm does Makechain use?

Simplex BFT — single-chain, 3f + 1 fault tolerance, round-robin leader election, 2-chain finality.

Storage

What are the storage limits?

Per storage unit:

Resource	Limit
Projects	10
Commits per project	10,000 (oldest pruned)
Refs per project	200
Collaborators per project	50
Keys per account	100
Verifications per account	50

See storage limits for the full allocation model.

What happens when I hit the commit limit?

Oldest commits not referenced by any active ref are pruned. Ref-targeted commits are never pruned. File content in the DA layer is unaffected.

Development

What Rust version do I need?

Nightly 1.93+. Commonware dependencies require nightly features.

rustup install nightly
rustup default nightly

Why is protoc required?

build.rs uses tonic-build to compile proto/makechain.proto into Rust types and gRPC stubs.

macOS: brew install protobuf
Ubuntu: apt install protobuf-compiler

How do I run tests?

cargo test              # All 520 tests
cargo test test_fork    # Filter by name

See the contributing page for the test distribution breakdown.