Alfa Code Founder Toolkit — Reference Implementation, Docs & Architecture

What it is: the Alfa Code Founder Toolkit is the working reference implementation of Alfa Code Specification v0.1, the Protocol One system that gives a building, room, object, vehicle, document, organization or digital subject a permanent address like ALFA-P1-BLD-MESA-85206-000001-SA, plus a tamper-evident record chain anyone can check offline. It is a single Python 3 file using only the standard library, with no network calls and nothing to install.

Why it matters: most identifiers point into someone else's database. An Alfa Code carries its own evidence: every event about the address (issuance, a two-sided transfer, a linked document, retirement) is a new hash-chained record, so if anything recorded is changed afterward, the verifier shows it. You get one of six clear verdicts (Verified, Warning, Unauthenticated, Integrity Alert, Broken Seal, No verdict) with a plain-English line explaining what it means and what to do next. A verdict speaks to the evidence only; it does not prove where an object is or who lawfully owns it.

An Alfa Code is a label, not proof of location, ownership or identity.

What’s included

Source + Docs: $149

• alfa.py: the full implementation. Address parser and ALFA-CHK-2 check characters (legacy ALFA-CHK-1 kept for the two published examples), ALREC-1 record chain, ALCAP-1 core payload, issuer enrollment, append-only assignment log, two-sided transfers, links, retirement, and the offline verifier (exit codes 0–8, ranked by severity: verdicts 0–5, then Refused, usage error and self-test failure).
• AlfaObject: a simple identity/state/action developer class that can carry a real Alfa Code and record each execute() into the chain.
• README.md, docs/QUICKSTART.md, docs/CLI-REFERENCE.md, docs/ARCHITECTURE.md.
• demo.sh and a captured demo transcript (sandbox data), plus a unittest suite (42 tests).
• CHANGELOG.md: what changed in this version.

Founder Edition: $299, everything above, plus:

• SPEC-ADDENDUM.md: the canonical byte format behind every digest, pinned exactly, so a second implementation can produce matching digests.
• test-vectors.json: published check-character, record, payload, enrollment and log vectors (every SHA-256 in full).
• architecture/: five diagrams as Mermaid source and 2400px PNGs: address anatomy, ALREC-1 record chain, verifier ladder, enrollment/issuance/transfer flow, and the AlfaObject front door.

Check on macOS/Linux with shasum -a 256 <file>.zip, or on Windows with certutil -hashfile <file>.zip SHA256.

What’s new in this version

• Exit codes ranked by severity, so a forged chain can never exit like a genuine one: 0 Verified, 1 Warning, 2 Unauthenticated, 3 Integrity Alert, 4 Broken Seal, 5 No verdict (alfa.py exit-codes prints the table; scripts written for the previous version must be updated).
• Stripped signatures caught: a missing signature from an issuer whose key is in the registry now reads Broken Seal; a wrong-key signature reads Broken Seal; no registry or an unknown issuer reads Unauthenticated. The verifier uses only the registry you pass it.
• Issuer-signed head statements: a copy of a chain that stops short of the issuer's latest statement reads Integrity Alert. A head statement only shows what was latest as of its own time, so Verified also needs a freshness source: a maximum statement age you choose (--max-head-age) or your own checkpoint (--checkpoint). Without one the best result is Warning, and the report shows the statement's time.
• Signed assignment log cross-checked against the chains (a deleted log or a broken entry chain is reported, never "intact"). audit also checks the store's own registry.json: an issuer whose signing key was removed, or one enrolled without a key, is reported unless you name it as a legacy keyless issuer (a key replaced with someone else's is caught only by --registry or your checkpoint); audit --registry compares the store with the registry you exported and kept; and your checkpoint records the registry, so an edited registry.json is reported and writes are refused. Also: an optional checkpoint that detects a restored stale backup (writes are refused and audit reports it), chain rules (nothing after retirement), strict text encoding, timestamp checks, small-order Ed25519 key rejection and privacy guards.
• Future-dated head statements: a statement dated more than 5 minutes ahead of the verifier's clock reads Integrity Alert, and alfa.py head will not create a statement dated in the future. (A verifier whose own clock is more than 5 minutes slow will report a genuine fresh statement this way; keep the clock set.)
• Log times cross-checked against the chains, and sign-legacy-log refuses logs that look rewritten rather than genuinely old.
• Reference-grade Ed25519 issuer signing, with issuer enrollment (proof of possession).
• ALFA-CHK-2 check, which catches every single-character substitution and adjacent swap (random two-character errors still slip through about 1 time in 500).
• Store-wide file locking, so concurrent issuance gets unique serials.
• tri_signature_ref is now format-checked, and every report labels it as not cryptographically verified.
• CHANGELOG.md is included in both Editions.

Run the self-test

Unzip, open a terminal in the folder and run:

python3 alfa.py --self-test

You should see Self-test: 225/225 passed. Then run ./demo.sh to watch an address get issued, verified, altered by one character (Broken Seal), and transferred with both parties' Tri-Signature references.

Who it’s for

Developers, architects and technical founders who want to read, run, test or re-implement Alfa Code, and anyone evaluating it before building on it.

Limits

What it does not do: no QR drawing, no motion or audio transport, no online resolver, and no governance workflow; those are outside spec v0.1's first build items. Time references use the local clock (CLK-LOCAL-1) and are labeled "not attested"; attested time (CLK-ATTEST-1) is accepted only when you supply the attestation reference. It is developer reference software, not legal advice, and it does not establish location or ownership.

Honest limits: the Ed25519 implementation is pure Python and reference-grade (not constant-time), so production keys belong in a vetted cryptography library or an HSM. The verifier trusts the issuer registry it is given. Without --registry or your checkpoint, audit trusts the issuer keys in the store's own registry.json: someone with write access to the data directory who replaces an issuer's key with one of their own and re-signs, or who consistently rewrites an issuer you accept as keyless (--allow-keyless), is not detected. With --registry (the registry you exported and kept) or your checkpoint, both are reported. Someone who can also write to the checkpoint itself, strip its new fields back to the rev-5 format and substitute a key without changing content, gets audit to report intact (out of scope: it needs write access to the checkpoint). After upgrading an old checkpoint, run audit --registry <your export> once before the first write. A head statement shows a chain is complete only as of the time the issuer signed it: with --max-head-age, an old statement replayed together with an equally old chain still passes while it is younger than the age you set (at most that age plus 5 minutes of allowed clock skew), and a checkpoint catches it only if it has seen the later records. A log rewritten by someone holding the issuer's key is not detectable, and the privacy filter is a heuristic. Signing keys are stored unencrypted (file mode 0600).

Instant .ZIP download on the order confirmation page, plus an email link (Shopify Digital Downloads). Covered by our 14-day refund policy.
Protocol One — Standards Office, 3707 E Southern Ave, Suite 1023, Mesa, AZ 85206 · protocolonestandardsoffice@gmail.com