macula_identity (macula v10.25.0)
View SourceEd25519 identities and the S/Kademlia crypto puzzle.
A Macula NodeId is an Ed25519 public key (32 bytes). Identities are optionally "puzzle-hardened": the pubkey satisfies SHA-256(pubkey) having at least N leading zero bits. This raises the cost of mass identity minting (Sybil defence).
See plans/PLAN_MACULA_V2_PART1_FOUNDATIONS.md sections 4.1–4.4.
Summary
Functions
Generate a fresh Ed25519 key pair. Does not grind a puzzle.
Generate a key pair, optionally grinding until the puzzle is satisfied.
Load a key pair from disk.
NodeId of an identity. Phase 1: NodeId == public key.
SHA-256 of the public key — the proof-of-work output measured.
Puzzle validity against the application-configured difficulty.
Save a key pair to disk with macula_owner_only_file:write/2: only its owner can read the file, it replaces whatever is at Path atomically, and a missing key directory is created with mode 0700.
Types
Functions
-spec generate() -> key_pair().
Generate a fresh Ed25519 key pair. Does not grind a puzzle.
-spec generate(#{puzzle => boolean(), difficulty => non_neg_integer(), _ => _}) -> key_pair().
Generate a key pair, optionally grinding until the puzzle is satisfied.
Opts:
puzzle:: boolean() — default falsedifficulty:: non_neg_integer() — leading zero bits required
-spec load(file:name_all()) -> {ok, key_pair()} | {error, bad_key_file | macula_owner_only_file:refusal() | term()}.
Load a key pair from disk.
The key file is read with macula_owner_only_file:read/1. It must be a regular file its group and others have no access to, mode 0600 or 0400; symlinks are followed. Otherwise the error names the file, what was found and what is required: {file_permissions, #{file, mode, required}} or {file_type, #{file, type, required}}.
NodeId of an identity. Phase 1: NodeId == public key.
SHA-256 of the public key — the proof-of-work output measured.
Puzzle validity against the application-configured difficulty.
-spec puzzle_valid(pubkey() | key_pair(), non_neg_integer()) -> boolean().
-spec save(file:name_all(), key_pair()) -> ok | {error, term()}.
Save a key pair to disk with macula_owner_only_file:write/2: only its owner can read the file, it replaces whatever is at Path atomically, and a missing key directory is created with mode 0700.