- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
review_round was passed through to the payload and otherwise ignored, so a REVIEW verdict ran to the same floor(n/2)+1 bar as a PASS -- the label changed, the mandate did not. A REVIEW verdict means the claim already tripped an advisory check (valuation past 2x the median, or netUtility a human had to supply). That is the claim that should need a wider mandate, so round 2 now requires ceil(2n/3): n=5: 3 -> 4 n=6: 4 -> 4 n=7: 4 -> 5 n=8: 5 -> 6 required_approvals(set_size, review_round); --min-approvals still overrides both. Proven end to end on the recorded live pair, which has five approvals from a seven-address set: it settles in round 2 at 5 of 7, refuses at 4 of 7, and the same four votes settle in round 1. 4 new tests (145 total), ruff clean, 0.5.0. |
||
| docs | ||
| .gitignore | ||
| gate.py | ||
| invoice.schema.json | ||
| ledger.py | ||
| LICENSE | ||
| live_omni_invoice.json | ||
| live_votes.json | ||
| pyproject.toml | ||
| README.md | ||
| reviewers.json | ||
| settle.py | ||
| tally.py | ||
| test_gate.py | ||
| test_ledger.py | ||
| test_reviewers.py | ||
| test_schema.py | ||
| test_settle.py | ||
| test_tally.py | ||
Foken — proof-of-contribution valuation gate
Off-chain Half 2 of the Foken governance design. Prototype, pure engineering — no blockchain, no tokens, no secrets, no deployment.
This is a coarse, deterministic pre-filter that sits in front of the
binding governance decision. It consumes a Foken Invoice (a JSON
document a contributor submits), validates it against hard IP/provenance
gates, applies the net-utility formula, and emits a verdict:
PASS, FAIL, or REVIEW.
Framing: this is a verifiable contribution pre-filter, not equity minting. There is no price, appreciation, or investment language here — and there shouldn't be. Nothing in this gate mints, prices, vests, or transfers anything.
The binding decision is always the human >50% vote. This formula is a pre-filter only — it never overrides the vote, and a PASS here does not mint anything.
Contents
- Files
- Run it
- Foken Invoice schema
- Validation & verdict logic
- The net-utility formula
- Reviewer set & quorum
- Off-chain tally (
tally.py) - Pending owner params
- Tests
- Design choices & resolved ambiguities
- Non-goals
- License
- Further reading
Files
| File | Purpose |
|---|---|
gate.py |
The CLI + gate logic, plus the reviewer-set model (validate_reviewer_set, quorum_reached). Net utility is computed in integer thousandths; stdlib only (argparse, json, re, sys; Python 3.11+) |
tally.py |
Off-chain tally / consensus service: counts distinct reviewer approvals, emits the mint-ready mintFromConsensus payload |
settle.py |
End-to-end settlement: gate → tally → ledger, in that order. Refuses to produce a number the first two do not authorise |
ledger.py |
Exact-rational ledger: compression savings, achieved ratio, per-recipient payouts, batch settlement — fractions only, no floats ever |
invoice.schema.json |
Formal JSON Schema (draft-07) for the Foken Invoice |
reviewers.json |
Example reviewer set (7 distinct 0x addresses) |
test_gate.py |
unittest suite for the gate (38 tests) |
test_reviewers.py |
unittest suite for the reviewer-set model |
test_tally.py |
unittest suite for the tally service |
test_ledger.py |
unittest suite for the ledger (flooring, ratio, settlement) |
test_settle.py |
unittest suite for the end-to-end path (live pair, refusals, exit codes) |
test_schema.py |
unittest suite for the JSON Schema (incl. a stdlib-only validator) |
pyproject.toml |
Minimal project metadata so uv run works in this dir |
Run it
# from this directory
uv run python gate.py invoice.json # or: python3 gate.py invoice.json
echo '{...invoice json...}' | python3 gate.py --json /dev/stdin # stdin via path
python3 gate.py - # '-' also reads stdin
python3 gate.py invoice.json --history history.json # optional median check
python3 gate.py invoice.json --human # pretty table instead of JSON line
# reviewer set + tally
python3 tally.py --reviewers reviewers.json --votes votes.json
python3 tally.py --reviewers reviewers.json --votes votes.json \
--review-round 2 --min-approvals 4
Output (default) is one JSON line:
{"invoiceId": "...", "verdict": "PASS", "reason": "...", "netUtility": 82.5, "netUtilityMillis": 82500}
Exit codes: 0 = PASS, 1 = FAIL, 2 = REVIEW.
--history PATH points at a JSON array of past invoices (or an object with
an "invoices" array). The last 10 invoices in the file set the median
for the valuation-deviation check — keep the file in chronological order
(append newest last). A malformed/absent history is warned about and
skipped, never fatal.
Foken Invoice schema
All fields required unless noted. The prototype validates shape, presence, and the gated fields below; it does not recompute anything from a repo.
{
"invoiceId": "uuid-v7 string",
"version": 1,
"contributor": "0x-hex-address",
"work": { "title": "", "description": "", "repo": "", "commit": "" },
"artifact": { "provenanceHash": "sha256://...", "artifactUri": "ipfs://..." },
"valuation": { "selfAssessedFokens": 5, "basis": "USD", "rationale": "", "evidence": ["urls"] },
"ipAssignment": {
"statement": "IRREVOCABLE ASSIGNMENT TO UNIVERSAL TREASURY",
"license": "MIT-or-none",
"signedAt": "ISO-8601",
"signature": "0x-hex"
},
"netUtility": { "futureWorkAvoidedHours": 0, "workAddedHours": 0, "maintenanceDebtHours": 0 },
"dedup": { "claimedNovelty": "", "relatedInvoiceIds": [] }
}
| Field | Type | Notes |
|---|---|---|
invoiceId |
string | Any non-empty string is accepted by the gate (not uuid-validated). |
version |
int | Currently 1. |
contributor |
string | 0x + exactly 40 hex chars. |
work.* |
strings | Claimed work metadata. |
artifact.provenanceHash |
string | Must start with sha256://. |
artifact.artifactUri |
string | e.g. ipfs://.... |
valuation.selfAssessedFokens |
int | Positive integer. Floats and booleans rejected. |
valuation.basis/rationale/evidence |
str / str / list | Soft fields; evidence is a list of URLs. |
ipAssignment.statement |
string | Must contain IRREVOCABLE ASSIGNMENT. |
ipAssignment.license |
string | MIT or none, per policy. Not gated. |
ipAssignment.signedAt |
string | Not date-validated (date-only strings accepted). |
ipAssignment.signature |
string | 0x-prefixed hex. |
netUtility.* |
numbers | Tool-computed inputs — see below. Non-negative; may be floats. |
dedup.* |
str / list | Soft fields. |
netUtility — tool-computed inputs
netUtility carries the values the tool computes from the claimed work
(future work avoided, work added, maintenance debt). This prototype takes
those numbers as already-computed inputs — it does NOT inspect the repo
or re-derive them. That computation is a separate tool (out of scope here).
The gate only checks they are present and non-negative, then applies the
formula — in integer thousandths of an hour, never floats:
net = futureWorkAvoided·1000 − (workAdded·1000 + ⌊3·maintenanceDebt·1000 / 2⌋)
The 1.5× debt weight is the exact rational 3/2 rather than the float 1.5, so a
half hour is representable and a verdict can never turn on float noise at
exactly zero. compute_net_millis returns that integer; compute_net remains as
the legacy float view (hours) for callers that only want to display it. Debt is
charged floored, which can only make the net smaller — the conservative
direction for a claim. gate.evaluate returns both netUtility (float, legacy)
and netUtilityMillis (int, canonical); settle.py uses only the latter.
Formal JSON Schema
invoice.schema.json is a draft-07 JSON Schema for
the Foken Invoice. It matches the field names, required-ness, and types that
gate.py validates, with two deliberate differences (documented in the
schema's own description):
ipAssignment.statementandipAssignment.signatureare required in the schema, even thoughgate.pydeliberately keeps them out of its nested-required list — an invoice without them can never pass the IP hard gate, so the contract requires them.netUtilityis not required at the top level (a missingnetUtilityis a REVIEW ingate.py, never a FAIL), but when present it must carry all three non-negative numeric fields.
There is no third-party jsonschema dependency — test_schema.py ships a
minimal stdlib validator covering the subset the schema uses
(type, required, properties, items, pattern, minLength,
minimum, exclusiveMinimum, enum).
Validation & verdict logic (in precedence order)
- Structure — missing/type-broken required fields → FAIL (
malformed invoice: ...). - Hard gates → FAIL:
ipAssignment.signaturepresent and0x-hex, ANDstatementcontainsIRREVOCABLE ASSIGNMENT— elsemissing/unsigned IP assignment — no IP, no mintartifact.provenanceHashpresent andsha256://-prefixed — else FAIL (invalid artifact provenance: ...)contributorvalid0x+ 40 hex — else FAIL (invalid contributor address: ...)selfAssessedFokenspositive integer — else FAIL (selfAssessedFokens must be a positive integer)
netUtilitypresent & non-negative — else REVIEW (a human can fix the numbers; the gate cannot run without them).- Net-utility formula (see below):
net <= 0→ FAIL; this FAIL wins even if the valuation also deviates — a rejected invoice does not go to an extra review round. - Valuation deviation (only if
--historygiven):selfAssessedFokens > 2 × median(last 10 history invoices)→ REVIEW (valuation deviates >2x median; extra review round). net > 0→ PASS ("eligible for human vote").
So: FAIL > REVIEW > PASS, with net-negative FAIL taking priority over valuation REVIEW.
The net-utility formula
net = futureWorkAvoidedHours − (workAddedHours + 1.5 × maintenanceDebtHours)
net > 0→ PASS — eligible for the human vote.net <= 0→ FAIL — "net-negative utility: future work avoided is eclipsed by work added + maintenance debt".
The 1.5 weight reflects that maintenance debt is worse than work added:
it recurs.
Working example (also the README-facing smoke test):
| input | value |
|---|---|
futureWorkAvoidedHours |
100 |
workAddedHours |
10 |
maintenanceDebtHours |
5 |
| net | 100 − (10 + 7.5) = 82.5 → PASS |
Counter-example ("moving rocks"): 0 − (40 + 1.5×60) = −130 → FAIL.
Reviewer set & quorum (the >50% rule)
The reviewer-set model lives in gate.py and is consumed by tally.py:
- Reviewer set — a list of ≥ 5 distinct
0x+ 40-hex addresses.validate_reviewer_set(reviewers, min_reviewers=5)returns an error string when the set is not a list, is too small, contains a malformed address, or contains duplicates.load_reviewers(path)reads a JSON array of addresses (or an object with a"reviewers"array;-reads stdin) — the same lenient shape convention as--history. - Quorum —
quorum_reached(approvals, set_size)returnsapprovals * 2 > set_size: consensus holds when strictly more than half of the reviewer set approves. 3 of 6 is exactly 50% and does not quorum. Both spellings are available — the Pythonicquorum_reachedand the spec-fidelity aliasquorumReached. reviewers.jsonis an example set of 7 addresses (prototype; replace with real reviewers before use).
The spec's k = floor(n/2) + 1 distinct approvals is exactly the smallest
count that satisfies the >50% rule (for n = 5: k = 3; n = 6: k = 4;
n = 7: k = 4), so tally.py uses the same threshold.
The second round asks for more
A REVIEW verdict means the claim already tripped an advisory check — the
valuation deviated past 2× the median, or netUtility was malformed and a human
supplied it. That is precisely the claim that should need a wider mandate, so
review_round=2 raises the bar to ⌈2n/3⌉ instead of relabelling round 1:
| reviewer set | round 1 (PASS) | round 2 (REVIEW) |
|---|---|---|
| 5 | 3 | 4 |
| 6 | 4 | 4 |
| 7 | 4 | 5 |
| 8 | 5 | 6 |
--min-approvals still overrides both. The live pair in live_votes.json has
five approvals from a seven-address set, so it settles in round 2 at 5 of 7 and
refuses at 4 of 7 — while the same four votes settle in round 1.
Off-chain tally (tally.py)
After the gate pre-filters an invoice and the human vote collects approvals,
tally.py counts distinct approving reviewers and — when k is met —
emits the mint-ready payload matching the on-chain
AttestationVerifier.mintFromConsensus input:
python3 tally.py --reviewers reviewers.json --votes votes.json
votes.json is a JSON array of:
[
{"invoice": { "...foken invoice..." },
"reviewerAddress": "0x...", "signature": "0x-hex"}
]
Consensus output (exit 0) — the payload shape, exactly:
{"invoiceId": "uuid-v7 string", "recipient": "0x...", "amount": 5,
"reviewRound": 1, "approvalCount": 3, "reviewerSetSize": 5}
No-consensus output (exit 1):
{"consensus": false, "reason": "consensus not reached: 2/3 approvals needed (reviewer set size 5)"}
Behavior:
- Signatures are format-checked only (
0x+ hex, any length) — real Ed25519/secp256k1 verification is out of scope for this prototype. - Strict by design: any malformed vote (bad address, a reviewer outside
the set, a bad signature, a malformed invoice) aborts the tally — votes are
never silently dropped. Duplicate approvals from the same reviewer count
once. Votes must all reference the same
invoiceId. recipient=invoice.contributor;amount=invoice.valuation. selfAssessedFokens(validated with the same rules asgate.py).--review-round N— 1 for a normal vote (default), 2 when the gate verdict was REVIEW (the extra review round).--min-approvals K— overrides the derived k (see "Pending owner params" below).-reads stdin for either file flag.
End-to-end settlement (settle.py)
python3 settle.py live_omni_invoice.json \
--votes live_votes.json --reviewers reviewers.json --human
invoice 01933b70-9831-7bc8-8123-018b1509a001
verdict PASS (round 1, 5/7 approved)
claimed 400 FKN
kept flat assessment
verified 400 FKN
pay 0x71C8364f3B8844892cfa7D2Fa9f430589aCEE940 400
total 400 FKN
The order is the point: gate, then tally, then ledger. A popular bad invoice
cannot buy consensus with a crowd, and a refused claim returns no number at all
rather than a zero that looks like a quote. --kept N/D turns a flat assessment
into a compression claim, and the payable amount becomes the tokens actually
removed (floored) — --kept 3/10 on the same invoice settles at 280.
Exit codes: 0 settled, 1 refused (gate or quorum said no), 2 bad input
(unreadable JSON, unusable ratio) — the distinction tells you whether to fix the
claim or argue with the reviewers.
Exact-rational ledger (ledger.py)
The gate prices, the tally counts, the ledger does the arithmetic — with
fractions and nothing else. A saving is a claim about tokens that were
removed, so it is computed from the fraction that survives:
import ledger
ledger.compression_savings(1000, 3, 10) # 700: 30% kept, 70% saved
ledger.compression_savings(10, 1, 3) # 7: floored, never rounded up
ledger.compression_ratio(1000, 300) # Fraction(3, 10) - a claim, not a percentage
entry = ledger.LedgerEntry("alice", claimed_tokens=1000, verified_tokens=700)
entry.fokens # 700: payouts use the verified amount
ledger.settle([entry]) # {'payouts': {'alice': 700}, 'totalFokens': 700, ...}
Three rules, all enforced rather than documented:
- Floor, never round up.
original - floor(original * kept)can only understate a saving. A collections ledger may be wrong in that direction and no other. denominator == 0raises. A zero ratio is a malformed claim, not a 0% saving — the difference matters when the number becomes a payout.- No floats, no
bool.compression_savings(100, 0.5, 1)is an error, not a rounding surprise;Trueis not the integer1.
Pending owner params (not hardcoded)
The following are owner decisions that are deliberately not baked in; each is a CLI arg / config with a sensible default, documented here so the owner can flip them without code changes:
| Param | Where | Default | Notes |
|---|---|---|---|
| Reviewer count (k) | tally.py --min-approvals |
floor(n/2)+1 of the reviewer set size |
Strict >50% per spec; overridable per run |
| Minimum reviewer-set size | gate.validate_reviewer_set(min_reviewers=...) |
5 |
Spec-mandated ≥ 5; a per-call parameter |
| "Inactive" window (reviewer liveness) | — | not implemented | No timing logic in this prototype; would land as a --inactive-window-style config when decided |
| Pool split (treasury allocation) | — | not implemented | Out of scope: this prototype never allocates anything; would be config, not code |
| Gate tooling (netUtility computation) | — | not implemented | The tool that computes netUtility from a repo is a separate tool (out of scope); the gate takes its values as inputs |
Tests
python3 -m unittest discover foken -v # from the workspace root
python3 -m unittest discover -v # from this directory
Test suites:
test_gate.py— 34 tests: PASS (positive net), FAIL net-negative ("moving rocks", net = −130), FAIL missing IP assignment, FAIL invalid contributor, FAIL non-sha256://provenance, FAIL non-positiveselfAssessedFokens, REVIEW missing/negativenetUtility, REVIEW valuation >2× median (incl. the "only the last 10 history invoices count" rule), verdict precedence, and CLI exit codes 0/1/2 (file,-, and--jsonstdin paths,--human).test_reviewers.py— reviewer-set validation (size, address format, duplicates, overrides), the >50% quorum rule incl. the 3-of-6 boundary, andload_reviewersfile/stdin shapes.test_tally.py— the k formula (and its identity with the quorum threshold), payload shape/values, strict-vote handling, dedup, review round / min-approvals overrides, and CLI exit codes 0/1/2.test_ledger.py— 10 tests: savings are exact and floored (10at1/3retained saves7, never6or8), a zero denominator is an error rather than a 0% claim, a ratio above 1 is rejected, floats andboolare refused, ratios stayFractions (3/10, not30.0%), payouts use the verified amount, and settlement sums duplicate recipients deterministically.test_settle.py— 16 tests: the recorded live pair (live_omni_invoice.jsonlive_votes.json) settles to exactly400(PASS, 5 of 7 approved, quorum 4), the total always equals the sum of its entries, a compression claim pays only what was removed, a net-negative invoice never reaches the ledger, three approvals refuse where four settle, an outsider vote refuses, and the three exit codes mean settled / refused / bad-input.
test_schema.py— schema/draft-07 structural checks againstgate.py's constants, plus a stdlib-only draft-07-subset validator over valid and invalid invoices.
Design choices & resolved ambiguities
netUtilityis input, not computed. The tool-computed values are accepted as given; repo analysis is a separate tool, out of scope.- Verdict precedence (unstated in the brief): a net-negative invoice is FAIL even when its valuation deviates >2× median — an already-rejected invoice doesn't get an "extra review round". Documented above.
net == 0is FAIL (spec saysnet <= 0→ FAIL).- "Last N invoices" = tail of the history array; file order is chronological (newest last). Median of an even count is the mean of the two middle values.
signatureonly requires0x-hex (any length) — the spec's example is a short hash, so no fixed length is enforced.invoiceIdis not uuid-validated — any non-empty string passes (keeps the gate usable with synthetic/smoke ids like"u").signedAtis not date-validated — date-only strings are accepted.--json PATHis a path carrier (the brief's invocation is--json /dev/stdin), not an output-mode flag; output is JSON by default.- History problems are non-fatal (warn + skip the deviation check).
Non-goals
- No blockchain, no token economics, no pricing, no vesting, no minting.
- No secret material anywhere — this gate reads only public invoice data.
- Not deployed, not git-homed (the owner does that separately).
License
MIT — see LICENSE. The invoice's ipAssignment.license field
follows the same policy (MIT-or-none): contributors assign their IP
irrevocably, and the tooling that judges them stays free.
Further reading
- The Foken governance design — the on-chain half (AttestationVerifier, mintFromConsensus) this prototype pairs with.
- David Edgerton, The Shock of the Old: Technology and Global History since
1900 (2006) — use-centric value vs. innovation-centric attention: the
maintenanceDebtHoursterm is exactly the use-centric lens. - Elinor Ostrom, Governing the Commons (1990) — collective governance of shared resources: why the reviewer quorum, not the formula, is the binding decision.
- Vitalik Buterin, Zoë Hitzig, E. Glen Weyl, A Flexible Design for Funding Public Goods (2019) — quadratic funding as the boundary case this gate deliberately stops short of.
- Mike Masnick, Protocols, Not Platforms (2019) — why a pre-filter plus a human vote, with no platform in the middle.
- Recency as Salience and A Mező és a Tömeg (Vének Tanácsa, 2026) — the proxy critique this gate is built against: a scalar proxy turns pathological when a relational system delegates its continuation to it. Foken's refusal to price anything is the same refusal, at the governance layer. (Sovereign Library)