Module identity 

Ed25519 identity and the S/Kademlia crypto puzzle, matching macula’s own macula_identity.erl (macula-io/macula).

Uses ed25519-dalek (with the rand_core feature) — the same crate macula’s own macula_crypto_nif Rust NIF already wraps in production, not a separate crypto implementation, though the two are not required to track the same ed25519-dalek version: Ed25519 signing is deterministic per RFC 8032, so a byte-identical seed/message pair must produce a byte-identical signature across any correct implementation, any version. Every keypair/sign/verify test in this module is checked against fixtures captured directly from the real crypto:generate_key/2 and crypto:sign/4 in macula-io/macula’s own rebar3 shell, not just hand-derived expectations — which is exactly what lets this crate move ahead of the NIF’s own ed25519-dalek pin without losing that proof.

A macula NodeId is an Ed25519 public key (32 bytes) — there is no separate account/identity layer underneath it. Identities are optionally “puzzle-hardened”: ground until SHA-256(pubkey) has at least N leading zero bits (S/Kademlia Sybil defense — this raises the cost of minting identities in bulk, not of connecting with one that already exists). Grinding is a one-time cost paid once per identity, not per connection: puzzle_evidence is a cheap, deterministic hash computed fresh on every CONNECT frame, and puzzle_valid is a cheap check, not a proof-of-work re-verification.

Every station checks this on every CONNECT/HELLO, for every kind of dialer — this is not a station-to-station-only concern. Skipping it produces a real, previously-observed failure mode: the QUIC/TLS connection reports healthy, but the station silently rejects the application-layer HELLO, so the link looks connected while delivering nothing. Always use KeyPair::generate_with_puzzle, never KeyPair::generate, for any identity that will actually dial a station.

Structs

KeyPair

An Ed25519 keypair. The public half is the macula NodeId.

Enums

LoadKeyError

Constants

DEFAULT_PUZZLE_DIFFICULTY

Matches ?DEFAULT_PUZZLE_DIFFICULTY in macula_identity.erl. Grinding at this difficulty is sub-millisecond — see the module doc.

Functions

puzzle_evidence

SHA-256(pubkey) — the proof-of-work output measured by the puzzle. Cheap; not itself the expensive step (see the module doc).

puzzle_valid

Whether pubkey satisfies the puzzle at difficulty (leading zero bits of its puzzle_evidence).

verify

Verify sig over msg against pubkey. Matches macula_identity:verify/3’s contract exactly: a structurally invalid public key (not a valid Ed25519 point) is treated as “verification failed” (false), not a separate error — it could not have produced a valid signature either way.