loopmarket

A universal combinatorial marketplace over the ontodag / recordstore / Ethereum Swarm stack.

Every economic intention is one uniform, content-addressed offer — a thing described as a conjunction of OntoDAG categories, with a service time window and region, priced on the maker's personal scale (a personal numeraire; the record encoding calls it the maker's personal token). A distributed, versioned offer book holds them (recordstore keyspace; Swarm-backed via BeeBytesStore + a signed SwarmFeedPointer). Competing solver agents hunt profitable loops — cycles whose exchange-rate product exceeds one, i.e. negative cycles under −log weights — and a clearing layer re-verifies every leg from scratch and commits the whole loop atomically.

$ odag put piano-lesson music-lesson        # the catalogue is ontodag's
$ loop set maker amara; loop place home 46.05,14.50,5km; loop set terms home
$ loop give piano-lesson 100                # I give this, priced on my scale
$ loop want produce local weekly 104        # I want this, priced on my scale
$ loop loops && loop clearing               # hunt profitable loops; run the clearing house

loop is the command line (pip install loopmarket): ontodag's grammar plus two conventions — a bare number first is the quantity, last is the price — and + between the parts of a want that must clear together; every name a catalogue node, an omitted price your last unit price, and nothing published before the fully resolved offer is shown. Type loop alone for a prompt, pipe it a script for a batch. The same in Python:

from recordstore import MemoryBytesStore, RecordStore
from loopmarket import (Ontology, OfferRegistry, MockClearing,
                        SolverAgent, Thing, give, want, ...)

ontology = Ontology().load({"produce": [], "vegetable-box": ["produce"], ...})
registry = OfferRegistry(RecordStore(MemoryBytesStore()))
registry.publish_many([...])          # gives and wants, one uniform form
registry.commit()

agent = SolverAgent(registry, ontology, MockClearing(registry, ontology))
agent.step()                          # snapshot → match → hunt loops → clear

Try it

pip install -e ".[test]"              # (--break-system-packages or a venv)
python3 -m pytest tests/ -v           # 216 tests (two need a live Bee node, thirty-nine the evm extra, one swarmfs — skipped per test without them)
LOOP_HOME=$(mktemp -d) loop --catalogue examples/triangle.od < examples/triangle.loop   # P0 as a script
PYTHONPATH=src python3 examples/demo_triangle.py     # the same, through the API
PYTHONPATH=src python3 examples/demo_federation.py   # P1: books, fold, forgery, follower

The script publishes the smallest nontrivial book — a piano teacher, a market gardener and a bicycle mechanic, no pair of whom can trade — and loops && clearing finds, verifies and clears the triangle at a 12% surplus: fifteen lines of set maker, give piano-lesson amara_flat 100, examples/delivery.loop clears a circulation: the grocer's box at the shop plus the courier's run to the door as one composed leg (2026-09-13), want produce local weekly .... It runs unchanged with the book on Swarm (loop -f swarm:TOPIC ...; 0.3.0 live-checked 2026-09-12 on a Bee 2.8.2 light node: published, solved and cleared in 1m51s with the same loop_id the in-memory run gives, a fresh session reading the six fills back in 11s). The federation demo runs per-maker books on their own feeds, two aggregators folding to byte-identical manifests, a censoring aggregator convicted by absence proofs, a forged offer dying at the fold, a tombstoned offer staying closed, clearing provably based on the fold, and a follower reading it all back — in memory by default, live against a Bee node when BEE_API and BEE_BATCH are set (0.3.0 live, with ontodag's core pack: 4m25s, every check true). New here? Start with the User Guide (a tutorial at the command line, with the API alongside), then the Reference Manual (commands, settings, API, record formats, invariants). loop help is the one-screen version; the design record with its reasons is docs/plans/cli.md.

Candidate generation can also run through ontodag's parametric dimensions: DimensionIndex files gives under exactly the terms they carry (geo(u24), ljubljana, time(...), from(my_home) — cells, places, regions and floors, ordered by the graph), and candidate_matches_indexed asks one ontodag get per want — the want's categories as the query, items only; where and when are the exact check's, since a give that contains the want's place sits above it — provably the same matches as the exhaustive baseline (the recall test enforces set-equality), with far fewer exact checks. The index is a derived, per-solver copy; the shared catalogue and its pinned roots never move because of it. Swap the in-memory store for recordstore.swarm_store("offers", signer=...) (extra: pip install -e ".[swarm]", plus a Bee node and a postage batch) and the same code runs with the book on Swarm.

What is built, and what is designed

Built (P0, plus the live-Swarm milestone): the full pipeline above runs in memory — and, since 2026-09-12, from the command line (loop) — and since 2026-08-01 also end-to-end on a real Gnosis-mainnet Bee node — catalogue and book on Swarm, book head in a signed feed, fills atomic (the gated tests/test_swarm_book.py). Since 2026-08-21 the federation layer runs too — in memory and live (the gated tests/test_swarm_federation.py, 96.5s on a Bee 2.8.1 node): per-maker books under their own feeds and signers, an Aggregator folding them under the U8 admission rules into a three-root manifest published on its own feed, withdrawal tombstones, and a scorched-earth follower reconstructing the cleared world from (address, topic) alone. Since 2026-09-04 the federation demo adopts ontodag's core pack as the catalogue and includes a censoring aggregator: audit_manifest convicts it from its own manifest with absence proofs, and a solver folding the announced maker books itself recovers the honest fold (T14). Since 2026-09-14 discovery is one registry event on the chain Swarm settles on (LoopBookRegistry, deployed on Gnosis): loop announce says "my book is here", and every session with the registry setting folds the announced books itself under the admission rules — the read path needs no aggregator to trust; the v4 record carries exact rationals (U9), a thing's step and min, wants of several parts, fills with the quantity taken, partial fills of divisible gives and aggregation by quantity. Since 2026-09-15 clearing reaches the chain: recordstore's trie proofs verified on the EVM (contracts/TrieProofVerifier.sol), the structural half of a leg verified from the anchored root and the record bytes (LoopVerifier.sol), and the optimistic beat (BeatClearing.sol, deployed on Gnosis) — one outcome per beat with a bond, a challenge window, fills recorded on chain at finalization — posted to from loop propose and, since 2026-09-18, challenged from loop challenge (the record rebuilt from the submitter's book, the contract's verdict asked for free, sent only where it convicts); the semantic half stays optimistic with an arbiter hook. Since 2026-09-18 (0.11.0) the chain verifies books on Swarm under their own BMT addressing (SwarmAddress.sol), composed wants leg by leg, and — in front of the beat — the sealed-proposal auction (SealedBeat.sol, loop commit / reveal / outcome: numeraire-free scoring, the baseline as reserve bid, the fairness filter); the baseline selects among every simple cycle with one packer (selection.py); and guarantees are admissibility by declaration (the v5 record): a maker's neutral point, cancellation ladder and accepted assets on its own scale, a giver's deposit reserved per fill — gated in matching, checked on chain, and since 2026-09-19 held: the crypto escrow (LoopEscrow.sol, deployed on Gnosis, a smart contract as a maker) holds the deposit, the gate counts a bond only up to what the contract holds, loop finalize reserves the share per fill, and every undisputed case settles by timeout or the parties' own acts — a contested claim is factbond's. Alpha; interfaces will move.

Designed (2026-08-07): most of what loopmarket is now lives as a decided, research-grounded plan corpus under docs/plans/ — one document per work package, each with measurable gates, named open problems, and a closing "what this document does not promise" section. Anything implying unbuilt code carries a dated marker ("decided 2026-08, lands with the v2 bump / P1 / P2"). Planned invariants U8–U14 are specified in the documents that motivate them and summarized across ARCHITECTURE.md's update notes and §11; they enter CLAUDE.md as binding invariants only when their enforcing code and tests land. factbond's mirror corpus is factbond/docs/plans/.

Vocabulary

Three words carry the design and are used precisely since 2026-09-07:

• loop — any cleared circulation: the essay's word and the name in code (Loop, LoopProposal, loop/, loop_id).
• cycle (simple loop) — the strict circle; all the P0 solver finds, and the only case where "the product of rates around it" means anything.
• circulation — the technical name for the cleared object: a flow conserved at every maker on that maker's own scale, with composed legs where one want takes several gives (docs/plans/P2-loop-selection.md §10–11).
• hyper-leg — a composed leg: several givers as tails, one wanting maker as head, one flow variable, so it fills every tail or none. The maker graph with hyper-legs is a hypergraph; its flow is an LP for divisible legs and an ILP where a hyper-leg is all-or-nothing.

And two more: clearing is the atomic commit that fixes obligations; settlement is the makers delivering.

The plan corpus

Phase ↔ document map. P1 (federation): P1-federated-book.md, supported by ontodag-coupling.md and catalogue-bootstrap.md, with cli.md as its tooling. P2 (verifiable clearing): the three P2 docs plus proof-fabric.md, constrained by P4-privacy.md's format-freeze list and gated by THREATS.md tripwires. P3 (guarantee fabric): P3-guarantee-coupling.md plus factbond's entire corpus — gated by factbond's Phase-0 simulation going green and the P2 format freeze. P4 (privacy): P4-privacy.md, whose Tier 1 may ship alongside P2. Cross-phase: proof-fabric.md, THREATS.md, adoption-and-thickness.md, catalogue-bootstrap.md, ontodag-coupling.md.

Reading order. First pass: ARCHITECTURE.md → THREATS.md → P1-federated-book.md. Clearing track: P2-loop-selection.md → P2-clearing-pricing.md → P2-batch-auction.md → proof-fabric.md. Guarantee track: factbond DESIGN.md → mechanism-design.md → insurance-products.md → phase0-simulation.md → P3-guarantee-coupling.md. Market track: adoption-and-thickness.md → catalogue-bootstrap.md → ontodag-coupling.md.

Order of documents is not order of construction — gates decide that; and a document's existence proves nothing about feasibility. The Phase-0 simulation and the named empirical gates can kill designs recorded here; the corpus is built so that they can.

Documentation

• docs/USER-GUIDE.md — the tutorial: from your first offer to a federated book on a live Swarm network, every snippet runnable.
• docs/REFERENCE.md — the reference manual: every public class and function, the keyspace, record formats, invariants, environment.
• ARCHITECTURE.md — the design and its rationale: the uniform offer form, time/place as fits-within dimensions, the book's keyspace and multi-writer story, the loop arithmetic (and why prices are never negative), the trust model, the proof fabric, economic security, and what the architecture does not promise.
• ROADMAP.md — the phase index with status: P0 (built) → P1 (federated book, live since 2026-08-21) → P2 (verifiable clearing, batch auctions) → P3 (guarantee fabric via factbond) → P4 (privacy), each linking to its plan document.
• CLAUDE.md — working rules for development: dependency boundaries, core invariants U1–U7, known simplifications.
• docs/loop-economy.md — the vision essay: the loop economy, its gallery of loops, the solver ecology, judges without swords, and the path in.